Wracamy do tematyki inżynierii oprogramowania. Dziś problem dokumentowania kodu i czasu.

Dokumentacja jaka jest każdy widzi

W sumie rzadko widzi i nie wynika to z tego, że za dużo piszczelówki pije. Zazwyczaj dokumentacji robi się „po zakończeniu projektu”. Względnie „kod sam się dokumentuje”. Pierwszy argument to bzdura, bo projekt o ile zostanie wykończony trafia do produkcji gdzie zazwyczaj trwają dalsze prace nad kodem. Drugi argument jest słuszny do momentu w którym trzeba szybko coś się o nieznanym kodzie dowiedzieć. Dokumentacja okazuje się niezbędna, bo powinna zawierać nie tylko informacje I/O, ale też haczyki np. sposób synchronizacji, nie oczywiste zastosowania kodu i informacje o potencjalnych błędach.
Niestety oba te argumenty powodują, że programiści nie tworzą dokumentacji kodu. Brak dokumentacji przekłada się na problemy z utrzymaniem, które wynikają z błędnego zrozumienia samo-dokumentującego się kodu lub braku dokumentacji i możliwości sprawdzenia co jak działa. Czyli mamy problem.
Rozwiązaniem jest pisanie dokumentacji. Łukasz Lenatr opisywał to już. Jest jednak jeszcze jeden problem.

JavaDoc? Ok. Tak będę miał czas

Brak czasu bardzo często jest argumentem osób, które dokumentacji nie tworzą. Wiadomo poganiacz stoi nad głową z batem i każe jak najszybciej oddawać gotowy kod. Ty człowieku chcesz się wyrobić w terminie więc odpuszczasz sobie drobnostki. Jak temu zaradzić?

DocDay

Ostatni dzień przed pójściem na weekend/urlop powinien być poświęcony na uzupełnianie dokumentacji. Dlaczego ostatni? Ponieważ już jesteśmy rozleniwieni i co najważniejsze nie wybije nas to z rytmu programowania. Jak wprowadzić DocDay do zespołu? Większość metodyk zakłada cykliczne spotkania programistów i bacikowego. Wystarczy zaproponować, że w piątki od 11 zespół tworzy dokumentacje i wszytko co nie jest krytyczne przechodzi na kolejny tydzień.

Zostawiam wam to pod rozwagę