Nie koduję ostatniego dnia

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ę

Napisz odpowiedź

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *

To create code blocks or other preformatted text, indent by four spaces:

    This will be displayed in a monospaced font. The first four 
    spaces will be stripped off, but all other whitespace
    will be preserved.
    
    Markdown is turned off in code blocks:
     [This is not a link](http://example.com)

To create not a block, but an inline code span, use backticks:

Here is some inline `code`.

For more help see http://daringfireball.net/projects/markdown/syntax