Wątek przeniesiony 2015-08-14 00:36 z Off-Topic przez somekind.

Dokumentowanie kodu

0

Czy dokumentujecie swój kod? Jeśli tak to w jaki sposób?

Ja staram się dodawać dokumentacja za pomocą "///" w Visual Studio ale nie piszę w notatniku co funkcja robi co przyjmuje i jakie ma problemy.

Wiele słychać ostatnio o tym czy dokumentować czy nie, że dokumentacja powinna być w kodzie tzn. co? Nazwy zmiennych, metod i klas powinny mówić co kod robi?

3

Jeśli już to dokumentuje tylko publiczne API klas jeśli ktoś może z tego też korzystać. Generalnie kod powinien sam sie komentować. Jak jest dobrze napisany to nie ma potrzeby wstawiać komentarzy. Problem z komentarzami jest taki że nikt ich nie utrzymuje. Klasa/metoda zmieni się 100 razy a komentarz pozostanie ten sam, błędny i nie przystający do rzeczywistości.

3

Pisz testy zamiast dokumentacji.

0

A co mają testy do dokumentacji? Pytam szczerze. Myślałem, że testy testują funkcjonalność.

3

Testy pokazują jak używać danego kodu i co ten kod robi. Bo w teście zwykle masz przygotowanie danych na wejście, wywołanie kodu a potem sprawdzenie wyników. Czyli ktoś czytając test widzi od razu co jest potrzebne żeby tej funkcjonalności użyć, widzi jak to poprawnie wywołać i widzi jakie są spodziewane efekty.

1

Dziś już nikt nie dokumentuje kodu w taki sposób opisowy jak Ty to przedstawiłeś w pierwszym poście.
Wyjątek stanowią publiczne API, ale to oczywiste bo jakoś trzeba przekazać innym programistom jak mają korzystać z narzędzi, których im dajemy.

Natomiast zwykła aplikacja powinna zawierać liczne testy, które same dokumentują kod i co najważniejsze - z naturalnych przyczyn - są zawsze aktualne i nie zawierają błędnych/mylnych informacji. Osobiście jak widzę w kodzie masę komentarzy w stylu // lub nie daj Boże ///, to mam odruch wymiotny.
Albo kod jest nieczytelny i trzeba go poprawić, albo ktoś miał za dużo czasy i pisał banały.
W pracy zazwyczaj pozbywam się głupich komentarzy (i tak są zapamiętane przez system kontroli wersji w razie czego).

3

Z brakiem komentarzy można przesadzić w drugą stronę. Kod niby ma się sam dokumentować, ale bardzo często programista tylko myśli, że pisze samodokumentujący się kod, a tymczasem po miesiącu nie da się go zrozumieć. Np. bardzo miło jest zobaczyć komentarze odpowiadające na pytania po co dany fragment kodu jest i dlaczego np. nie mógłby być napisany inaczej. Albo informacja o tym, jaki ogólnie znany algorytm został zastosowany, wraz z linkiem do Wikipedii itp. Albo, że kolejność danych dwóch linijek jest bardzo ważna i dlaczego.

0

Na pewno chciałbym zobaczyć komentarz/todo w miejscu gdzie coś jest niedokończone... tak, żebym od razu o tym wiedział a nie tracił czas na to, że nie działa.

0

Komentarze TODO to fajna rzecz - niestety nawet one potrafią być mylne, nieprawdziwe i nieaktualne. Tak wynika z moich doświadczeń zawodowych, gdzie programiści nie wiedzą już dlaczego dany TODO istnieje, a sprawdzając od kiedy istnieje dowiadujemy się, że od wielu wielu lat :)

Od kilku lat mam wypracowany mechanizm - gdy chcę napisać komentarz dostaję automatycznie znak stop i czerwone światło w głowie, że coś jest nie tak z kodem. Okazuje się to być zawsze prawdą i po poprawce kodu komentarze stają się zbędne.
Niemniej w pracy zawsze spotkamy się ze sporą ilością komentarzy w kodzie.

0

Jak pisze się w Javie to gag-annotations :)

0

staram się pisać javadoc-e zgodnie ze standardami:

  • opisać kontrakt dla klasy, za co klasa jest odpowiedzialna, za co każda z metod jest odpowiedzialna,
  • co reprezentują poszczególne argumenty metod,
  • co reprezentuje wartość zwracana przez metodę,
  • niezmienniki: warunki początkowe (preconditions @pre), warunki końcowe (postconditions @post), niezmienniki (invariants),
  • rzucane wyjątki w przypadku niemożności dotrzymania kontraktu.

1 użytkowników online, w tym zalogowanych: 0, gości: 1