Programowanie systematyczne – rozdział trzeci (i ostatni): dokumentacja

https://xpil.eu/Y4rFp 📋

Było o systemach kontroli wersji, było o integracji kodu... ostatni rozdział mojej miniaturowej trylogii dotyczy dokumentowania kodu.

Proces dokumentacji jest na ogół najbardziej bolesnym, najczęściej przemilczanym i najbardziej po macoszemu traktowanym elementem tworzenia rozwiązania informatycznego. Niestety, wraz ze wzrostem komplikacji budowanego przez nas systemu, solidna dokumentacja staje się absolutnie niezbędna.

Wynika to zazwyczaj z dwóch faktów:1.Wymagania klienta oraz 2.Rotacja kadr

O ile klient nie zawsze wymaga szczegółowej dokumentacji technicznej (i często zadowala się dokumentacją funkcjonalną lub nawet całkowitym jej brakiem), o tyle rotacja kadr wymusza dokumentowanie kodu. Czym więcej ludzi przy projekcie tym większa szansa, że ktoś lada dzień odejdzie a ktoś inny (być może całkiem nowy) przejmie jego schedę.

Z drugiej strony, dokumentowanie jest procesem czasochłonnym. Jeżeli napisanie danego modułu ma mi zająć 20 godzin, udokumentowanie go zajmie mi kolejne 2 godziny. Tym samym rośnie koszt wytworzenia oprogramowania

Z trzeciej jednak strony, brak dokumentacji z pewnością spowoduje przestój w przypadku, kiedy autor kodu odejdzie z firmy (pół biedy jak złoży miesięczne wypowiedzenie, gorzej jak pójdzie na miesiąc chorobowego albo wpadnie pod meteoryt), ergo spowoduje opóźnienie większe niż te 3-4 godziny poświęcone na napisanie dokumentacji. Tak więc summa sumarum strata czasu poświęconego na tworzenie dobrej dokumentacji kodu jest pozorna. O dokumentacji trzeba myśleć w kategoriach ubezpieczenia od nieszczęśliwych wypadków: być może nigdy nie będziemy jej musieli użyć, ale jak się już coś wydarzy, jesteśmy kryci.

No ale starczy lania wody - jak to właściwie działa naprawdę?

Niestety, nie mam pojęcia o żadnych standardach (mniej lub bardziej "przemysłowych") tworzenia dokumentacji. Wiem natomiast co działa a co nie działa - i o tym napiszę.

Po pierwsze, dokumentacja musi być zrozumiała. Pisząc, wyobraźmy sobie, że będzie to czytać ktoś bez żadnej wiedzy o projekcie (lub, w najlepszym razie, z wiedzą ogólną lub cząstkową).

Po drugie, nie rozpisujmy się za bardzo. Dokumentacja to nie ryż, nie liczą sie kilogramy tylko wartość merytoryczna.

Po trzecie: w przypadku dokumentacji technicznej, wyjątkowo skuteczne jest dokumentowanie w samym kodzie. Zamiast mieć dwa osobne dokumenty (1. kod i 2. dokumentacja do kodu) lepiej mieć to ładnie wymieszane do kupy, żeby - czytając kod - czytać równocześnie jego dokumentację. Najlepiej na początku modułu umieścić zwięzły nagłówek (kto, kiedy, numer projektu lub naprawianego błędu, ew. zwięzły log zmian - szczegóły zawsze da sie wyciągnąć automatem z VCS), a w samym kodzie opisać krótko co poszczególne operacje robią.

Nie umieszczajmy w komentarzach śmieci typu:

i++; // zwiększamy i o jeden

Informacjonośność powyższego komentarza jest wręcz ujemna ponieważ czas przeznaczony na jego przeczytanie możnaby spożytkować na dwie kolejne instrukcje. Dodatkowo, zakładamy z dużym prawdopodobieństwem, że osoba czytająca kod wie co robi operator ++.

Przykład "dobrego" komentarza:

i++; // dodane [20110627] przez [xpil]; wymagane przez bugfix #288564

Albo tak:

i++; // [20110627] [xpil]: korekta błędu #288564 (przypadek brzegowy - szczegóły w opisie błędu)

Czasami bywa jednak, że oprócz porządnie udokumentowanego kodu wymagany jest też osobny dokument techniczny. W takiej sytuacji należy pamiętać o kilku całkiem prostych zasadach:

- Wersjonujmy dokumenty i przechowujmy kopie archiwalne w osobnym katalogu (lub na serwerze VCS)

- Nie dodawajmy żadnych niepotrzebnych kwiatków. Ktoś, kto to będzie kiedyś czytał, będzie się prawdopodobnie spieszył i/lub będzie szukał bardzo konkretnej informacji. To jest dokumentacja techniczna a nie Wojna i Pokój.

- Wersję początkową dokumentu można na ogół wygenerować jakimś narzędziem. Na przykład szczegółowe informacje o kolumnach tabeli można prosto wygenerować jednym zapytaniem SQL; potem trzeba tylko dodać część opisową tam gdzie jest to niezbędne.

- Spis treści. Warto go mieć - znacznie przyspiesza szukanie w dużych dokumentach. Zwłaszcza gdy ktoś, nie daj boziu, używa wersji drukowanej naszego dokumentu.

- Dopasujmy poziom szczegółowości do wymagań i możliwości naszego docelowego audytorium (a w zasadzie "lektorium"). Jeżeli nie wiemy kto to będzie czytał, należy kierować się zasadą umiarkowanego pesymizmu co do wydajności intelektualnej końcowego odbiorcy. W najgorszym razie może to trafić nawet do kadry zarządzającej, a tam to już różnie bywa 😉

- W żadnym wypadku nie umieszczajmy w dokumentacji kompletnych listingów ani nie odwołujmy się do numerów linii. Lepiej otagować sam kod a w dokumencie odwołać się do tagu.

Ja osobiście nie cierpię tworzyć dokumentacji . Natomiast jeszcze bardziej nie cierpię przejmować po kimś projektu nieudokumentowanego lub udokumentowanego kiepsko. Lepiej więc wybrać mniejsze zło...

Ostatnia uwaga: z wyjątkiem nielicznych sytuacji, jeżeli spędzamy nad dokumentowaniem naszego projektu więcej niż 10% czasu, prawdopodobnie robimy coś źle. Jeżeli przejmujemy po kimś całkiem nieznany projekt i zrozumienie go na podstawie istniejącej dokumentacji zajmuje nam więcej niż 20% czasu przeznaczonego na projekt, nasz poprzednik zrobił coś źle 😉

Dziś na koniec dwa żarty ukradzione z JoeMonster.org:

- Nazwa państwa na jedną literę?
- Samoa.

- A skąd jest facet żywiący się kartą dań?
- Z Jemenu

https://xpil.eu/Y4rFp 📋