Mam pytanie odnośnie dokumentowania kodu źródłowego...
Czy w dobrym smaku jest komentowanie metod prywatnych ? W sensie opisu param i return?
Czy jest odpowiednik eclipse-cs w netbeans? Lub jakieś inny dobry plug-in?
Pozdrawiam
0
0
Ja dokumentuje namietnie wszystko i wszedzie, oczywiscie sensownie (np. nie dokumentuje najczesciej setterow i getterow ktore nic nie robia bo nie widze sensu, chociaz i tak ich unikam, ale czasami trzeba, nie zawsze dokumentuje co jest zwracana lub co oznacza parametr jesli jest to z nazwy i kontekstu jasne). Za jakis czas chce wrocic i moc przeczytac co i jak, i chce zeby koledzy mogli do tego kodu isc i rowniez moc przeczytac.
0
A ja wolę stosować opisowe nazwy zmiennych od nadmiernego komentowania, np jeśli zmienna trzyma ilość krzeseł do wyrzucenia przez okno to mogę ją nawet nazwać: ilośćKrzesełDoWyrzuceniaPrzezOkno. Z nazwami funkcji tak samo.
Pamiętajcie, że czytanie dokumentacji zajmuje czas oraz, że jak coś się szybko czyta to się szybko zapomina. Jeżeli ktoś lata po waszym kodzie (eksploruje), bo chce się dowiedzieć jak coś działa, to lepiej się mu wtedy czyta kod z długimi opisowymi nazwami zmiennych niż gdy przy każdej funkcji musi czytać komentarz.
Niestety jednak jeżeli ktoś pisze rozwlekły kod to te długie nazwy zmiennych w sumie mogą zaszkodzić. Ja zawsze staram się pisać zwięzły kod, używać funkcji bibliotecznych, funkcyjnych konstrukcji (w czystej Javie też można, np Functional Java albo własne klasy), czy specjalnych konstrukcji języka.
Dzięki mojemu podejściu jeżeli ktoś np dostał Exceptiona i czyta klasy ze stacktracea, to nie musi przy każdym poziomie czytać dokumentacji do funkcji, bo w zrozumieniu funkcji pomagają mu nazwy zmiennych.
Pisanie długich nazw nie stwarza mi wielkiego problemu, bo piszę szybko bezwzrokowo oraz włączyłem sobie auto-podpowiadanie w NetBeansie (automatyczne, bez Ctrl-Spacja).
0
Pytanie co znaczy nadmierne. Nie uwazam ani uzytwkownicy mojego kodu rowniez aby komentarze byly nadmierne. Ponadto, gdy definiujesz kontrakt musisz opisac jego ogolne zalozenia i co musza implementacje spelnic aby byc poprawne niz
public Object evaluateNotNullPathRelativeToNotNullRootObjectWithNonNullStateMapWhereEvaluationLogicMayUseTheStateForItsOwnPurposesAsWellAsToDeliverAdditionalEvaluationInformationBackToTheCaller(String path, Object root, Map<?, ?> state) throws EvaluationException;
Dodatkowo, implementacje takiego interfejsu moga dzialac zupelnie inaczej i rowniez moim zdaniem powinno byc opisane ogolnie jak dana implementacja dziala. Albo JavaDoc klasy albo metody.
Gdy musisz napisac cos wiecej niz CRUD z paroma formatkami plus gettery i settery, tylko wlasnie cos wymyslic i zajmie Ci to duzo czasu, chcesz aby bylo to jasno i przejrzyscie opisane co, jak i dlaczego. Nie powiesz mi ze Twoj kod zawsze po nazwach mowi co robi i jak to robi, bo to by moim skromnym zdaniem znaczylo ze a) piszesz banalny kod lub b) myslisz ze wszystko jest latwe bo masz akurat w glowie, nie dbasz o wspolpracownikow / nastepncow, czyli jednym slowem masz malutkie doswiadczenie, albo c) cala kariere siedzisz w jednym i faktycznie pamietasz wszystk co napisales.
0
@Wibowit, tyle tylko, że samokomentujący się kod to jedno, a wymagania dotyczące dokumentacji kodu to drugie. Zazwyczaj jest tak, że bardziej niż na kodzie PMom (szczególnie nie technicznym) zależy na dokumentacji i chciał nie chciał trzeba coś napisać.
Po pierwsze narzędzia. Ja używam JAutodoc, który generuje komentarze na zasadzie "byle coś było". Nieźle sprawdza się do komentowania getterów/setterów. Do tego checkstyle, który raz na pewien czas sprawdza mi pokrycie kodu komentarzami i tworzy tzw. dupokrytkę na okazję złego dnia u PMa.
Po drugie dokumentuję wszystko. Przy czym w dokumentacji znajduje się informacja o tym co metoda robi w określonych warunkach. Co stanie sie jak jako parametr podasz null, a co jak podasz "pusty" obiekt. W przypadku klas staram się opisać krótko co dana klasa robi oraz umieszczam odsyłacz do np. założeń.
Po trzecie testy też są częścią dokumentacji. Z jednej strony pokazują jak używać klasy. Z drugiej pozwalają na określenie, które elementy klasy pokrywają które części specyfikacji.
Po czwarte i najważniejsze. Dokumentacja powstaje w formie skróconej w trakcie implementacji, a gdy kod uzyskał status taga to uzupełniana i aktualizowana jest dokumentacji. Pomocna w tym momencie jest lista zmian z SCMa, bo wiadomo gdzie się grzebało.
0
kropki:
Nie napisałem, żeby zarzucić komentowanie kodu, dokumentacja jest bardzo ważna. Jednak jestem np przeciwny stosowaniu kilkuliterowych nazw zmiennych, a potem w dokumentacji opisywanie tej zmiennej kilkoma słowami. Inaczej mówiąc: stawiam nazwy zmiennych wyżej niż dokumentację. Jeżeli nazwy zmiennych są skopane to i z dokumentacją rozumienie kodu jest znacznie wolniejsze.
kozioł:
Generowanie komentarzy z automatu to już mija się z celem. Lepiej, żeby takich w ogóle nie było.
0
Ok, w takim razie sie rozumiemy i zgadzamy ;d