Przyczyna tego stanu może leżeć w wyniesionych ze szkoły wspomnieniach niepowodzeń przy pisaniu wypracowań, w których w odróżnieniu od kodu programu – za dużo wolności, wywoływało zagubienie, a próba zamiany idei na słowa była bardziej męcząca niż owocna. Wypowiedzi pisemnej nie można rozwijać zaczynając z dowolnej strony – bo to nie wychodzi, a zaczynanie od tezy, w zasadzie przecież już nie wymaga rozwinięcia. Pisanie od początku do końca – a tak przecież pisze się w szkole gdzie nie można sobie pozwolić na dopiski na marginesach i kilkukrotne poprawianie zdania, bo na papierze zostanie tylko jedna wielka plama. Myśl zapisujemy na papier w postaci swego rodzaju strumienia świadomości, i o ile udowodnienie, że Słowacki wielkim poetą był, bo nas zachwyca zwyczajnie nam nie wychodziło, to omówienie technicznych szczegółów jakiegoś rozwiązania programistycznego może stanowić spore wyzwanie. Zresztą – po co dokumentować kod, skoro przecież kod sam w sobie jest dokumentacją. Nawet lepszą – bo taką którą sprawdza sam kompilator oraz testy jednostkowe.

Niestety nie jest to prawda. Kod – służy w głównej mierze do poinstruowania kompilatora – co komputer ma robić. Istniejące w nim różne środki wyrazu pozwalają po prostu wyrażać się nieco precyzyjniej zabezpieczając się, w ten czy inny sposób, przed błędnym użyciem poszczególnych funkcji czy modułów. Brakuje jednej – ale bardzo istotnej informacji – po co komputer ma to robić.

Oczywiście – to nie jest nasz problem. Programista ma pisać programy a nie zastanawiać się nas sposobem naprawy świata, jednak czasy, gdy pracą nad programem zajmował się zarówno programista, jak i analityk oraz projektant – bezpowrotnie minęły. Komputery są szybkie i mają ogromną pojemność pamięci, więc pewne niedociągnięcia związane z architekturą przestają być tak bardzo istotne. Jakbyśmy na budowach mieli niezwykle lekki i wytrzymały materiał – nie byłby potrzebny projekt – wystarczyłoby, że co tam poskłada zwykły robotnik – i moglibyśmy bezpiecznie mieszkać w fantastycznych budowlach. Problem by się zaczął, gdyby trzeba było coś naprawić. Albo, co gorsze, przebudować. A konserwacja istniejącego kodu – to niestety jest już nasz problem. Tym poważniejszy, że zazwyczaj jesteśmy zmuszeni poprawić kod który napisał ktoś inny.

Kod źródłowy dokumentuje stan faktyczny. Możemy się z niego dowiedzieć tylko to co jest zaprogramowanie, a nie co miało by być, i dla dlaczego. Nie ma tu również miejsca na rozważania dlaczego podjęto takie a nie inne decyzje projektowe. I tu trafiamy na kolejną przyczynę niechęci do dokumentacji. Bo w rozmowie między dwoma kolegami określenie „wydało mi się to sensowne”, albo „wpadłem na taki pomysł” brzmi całkiem spoko, ale na papierze – już budzi niepokój. Bo może ktoś miał lepszy pomysł, ale nie został on uwzględniony? Jeszcze trzeba by coś uzasadnić a może nawet wdać się w polemikę z innymi rozwiązaniami? W końcu nie jesteśmy od wątpliwości, ale od rozwiązywania konkretnych problemów.. Prawda?

Prawda. Od rozwiązywania a nie od stwarzania.

Programuję od wielu lat i spotykam się cały czas z młodymi zespołami w których radość z działającego programu jest celem samym w sobie, i wszystko co ten cel oddala – musi być postrzegane jako przeszkoda, a wyzwania związane z analizą istniejącego kodu, pozwalają poszerzyć wiedzę. Jest to też swego rodzaju rytuał przejścia – kiedy zaczynamy radzić sobie z samodzielną analizą nierzadko setek tysięcy linii kodu.

Pojawiające się tu słowo „kod” jest bardzo trafne, bo myśli i rozwiązania programistów są w nim w pewien sposób zakodowane i niestety jest to kodowanie stratne. I nie pomagają ani komentarze, które rzadko bywają pomocne, czy specjalny kod pozwalający na automatyczne generowanie dokumentacji – bo i ta nie zawiera informacji – dlaczego.

Szczególnie dotkliwe jest to w nowoczesnych językach programowania w których istnieje wiele sposobów na zapisanie tych samych działań, i w których programiści kuszeni są do tworzenia różnego typu automatyzacji, które co prawda zapewniają na przykład poprawną inicjalizacje poszczególnych modułów, lub rejestrują dla pewnych celów tworzone obiekty, ale utrudniają zrozumienie „co się dzieje” wszystkim tym którzy są nowi w projekcie.

Dlatego stawiam na dobrze przygotowaną i przede wszystkim – żywą dokumentację, która nie musi zawierać powtórzeń tego co widać z kodu (który powinien być sam z siebie czytelny), a powinna zawierać to, czego z kodu nie można wyczytać zbyt łatwo, a więc:

• Cele i założenia – czyli jakie są zadanie programu oraz na jakich danych (i na jak dużych danych) program będzie pracować.
• Podjęte decyzje architektoniczne.
• Pomysły które są w jakikolwiek sposób nietypowe. Z opisem dlaczego wydaje się nam dobrym pomysłem je wdrożyć.
• Wszystkie komunikacje niejawne – to znaczy takie które nie wołają bezpośrednio funkcji, zamiast tego przekazują informacje przez kolejki lub przez interfejs wirtualny (choć w tym wypadku wystarczy dodać zapis do logów i będzie się dało prześledzić co jest tka na prawd wołane.

I nie musza to być jakieś elaboraty – bo nikt tego nie będzie czytał. Ot krótkie maksymalnie 3-stronicowe dokumentu zawierające jakieś ilustracje. Czy to takie trudne?