Dorobek tradycji...

Tradycyjne metodyki tworzenia oprogramowania kładą nacisk na stronę formalną dokumentowania kodu. Wymagają zachowania kolejności etapów: analizy, projektowania, kodowania i testowania, a także precyzyjnego opisywania poszczególnych partii kodu: czego dotyczą, jakie mają parametry oraz jak wyglądają ich powiązania z pozostałymi częściami składowymi projektu. Nie można nie zauważyć, że wiele z tych założeń wyrosło na gruncie programowania proceduralnego, w którym struktura kodu i zależności między jego fragmentami często nie były widoczne od razu.

Przejrzystość kodu - czasem wręcz w znaczeniu dosłownym - zależała prawie wyłącznie od dobrej woli programisty. A zatem, ponieważ do nasilenia tej ostatniej można śmiało zastosować rozkład statystyczny opisany krzywą Gaussa-Laplace'a, wprowadzenie dobrej praktyki w postaci projektu formalnego oraz szczegółowych komentarzy było koniecznością. Wypada też dodać, że zręby wymogów dotyczących dokumentowania powstawały w czasach, kiedy programowanie było zajęciem elitarnym, zarezerwowanym dla ludzi ze środowisk uniwersyteckich. Pragmatyzm biznesowy nie był wtedy głównym wyznacznikiem sposobu pracy programisty.

Wypracowany przez wiele lat dorobek intelektualny projektantów i programistów, a także nauczycieli ery proceduralnej został przez nich przeniesiony na grunt programowania zorientowanego obiektowo. W tym właśnie należy upatrywać zarodka większości obecnych sporów o dokumentowanie.

... kontra nowe wyzwania

Koronnym argumentem przeciwników szczegółowego dokumentowania jest stwierdzenie, że z dokumentacji tworzonej według zasad tradycyjnych w praktyce rzadko się dziś korzysta. W dużej mierze dlatego że większość informacji zawartych niegdyś w komentarzach wynika dziś wprost ze struktury kodu. Wystarczy więc zerknąć i wszystko jest jasne. Kod obiektowy rzeczywiście ma stosunkowo prostą, łatwą do zrozumienia strukturę i znalezienie współzależności między jego poszczególnymi partiami nie stanowi większego problemu. Odnajdowaniu współzależności w kodzie obiektowym służy też mechanizm dziedziczenia cech obiektów nadrzędnych przez obiekty podrzędne.

Kolejny powód, dla którego tradycyjne dokumentowanie straciło na znaczeniu, to zasadnicze zmiany w warsztacie pracy programisty. Kod pisany "odręcznie" to dzisiaj tylko pewien fragment. Większość kodu - w odniesieniu do typowych aplikacji - jest generowana automatycznie. Daleko idąca automatyzacja pozwala nadawać funkcjom, atrybutom i zmiennym zrozumiałe nazwy, a wzrost mocy obliczeniowej komputerów sprawił, że objętość pliku z kodem nie ma dziś - tak jak niegdyś - większego znaczenia. Współczesne narzędzia prowadzą programistę za rękę. Automatycznie formatują kod, proponują listy atrybutów i samoczynnie dokańczają wyrażenia, o wskazywaniu czy nawet samoczynnym poprawianiu błędów składni nie wspominając. Co więcej, wystarczy kilka kliknięć myszą, aby na podstawie analizy kodu narzędzia stworzyły szkielet dokumentacji według określonych standardów. Na życzenie przedstawią nawet strukturę i zależności projektu w formie graficznej.

Jako że oprogramowanie stało się towarem powszechnego użytku, istotne zmiany zaszły w metodach jego projektowania. Sytuacja, w której analiza, projektowanie, kodowanie i testowanie następują kolejno po sobie, zdarza się w praktyce bardzo rzadko. Znakiem czasu jest zachodzenie etapów na siebie, a nawet ich zrównoleglenie. Od rozpoczęcia negocjacji do oddania systemu do użytku wstępny projekt systemu podlega tak wielu zmianom, że jego formalizacja - zwłaszcza zbyt wczesna - jest bardziej utrudnieniem niż pomocą. Aby tego uniknąć, we wczesnym okresie projektowania tworzy się prototypy. Z konieczności rozszerzono więc zakres i częstotliwość testowania - trwa ono praktycznie przez cały czas tworzenia systemu, a także po oddaniu go do użytku.

Wraz z rozwojem Internetu pojawiło się sporo projektów o jednorazowym, niepowtarzalnym charakterze. Przykładem mogą być wydarzenia medialne, np. olimpiada, lub reklamowe - witryna promująca nowy model produktu. W takich przypadkach dodatkowe zabiegi dokumentacyjne po prostu trudno usprawiedliwić. W projektach internetowych relatywnie częściej niż w przypadku aplikacji klient/serwer zmieniają się duże fragmenty kodu. Ponadto w projektach tych prawie zawsze używa się równocześnie kilku technologii. Stąd, nawet w projektach o przewidywanym dłuższym czasie użytkowania, częstokroć łatwiej jest stworzyć nowy kod, niż "wgryzać" się w zawiłości toku myślenia innego autora, a nawet własnego dzieła, np. sprzed pół roku.

Przyłożyć się warto

Dylematy dotyczące dokumentowania są, a w każdym razie powinny być, udziałem wszystkich potencjalnych uczestników projektu. Poleganie na jednostronnych zapewnieniach dostawcy jest tak samo błędne, jak żądanie od niego, aby pedantycznie wszystko dokumentował. Zakres i szczegółowość dokumentacji powinny być kompromisem opartym na zdrowym rozsądku: ważącym ryzyko, ale i nakłady.

Nie wolno też zapominać, że dokumentacja zawsze jest dziełem zbiorowym, a grono jej potencjalnych odbiorców również jest liczne. Decyzje dotyczące dokumentowania, podjęte bez konsultacji z zainteresowanymi, mogą więc zaowocować marną dokumentacją z jednej strony, a jej bojkotem z drugiej. Przyłożyć się warto.