Kod samodokumentujący vs Javadocs?

18

Ostatnio pracuję nad refaktoryzacją części bazy kodu, z którą obecnie mam do czynienia - nie tylko po to, aby lepiej ją zrozumieć, ale także aby ułatwić innym, którzy pracują nad kodem.

Zwykle opieram się na myśleniu, że samodokumentujący się kod jest fajny . Po prostu uważam, że jest czystszy i jeśli kod mówi sam za siebie, cóż ... To świetnie .

Z drugiej strony mamy dokumentację, taką jak javadocs. To też mi się podoba, ale istnieje pewne ryzyko, że komentarze tutaj się przedawnią (podobnie jak komentarze w ogóle). Jednak jeśli są aktualne, mogą być niezwykle przydatne, powiedzmy, rozumiejąc złożony algorytm.

Jakie są najlepsze praktyki w tym zakresie? Gdzie rysujesz granicę między samodokumentującym kodem a javadocs?

Andreas Johansson
źródło

Odpowiedzi:

24

Kod samodokumentujący (i komentarze wewnątrz kodu) i komentarze Javadoc mają dwóch bardzo różnych odbiorców docelowych.

Kod i komentarze pozostające w pliku kodu są przeznaczone dla programistów. Chcesz rozwiązać ich obawy tutaj - ułatw sobie zrozumienie, co robi kod i dlaczego kod jest taki, jaki jest. Użycie odpowiednich nazw zmiennych, metod, klas itd. (Kod samokontrujący) w połączeniu z komentarzami pozwala to osiągnąć.

Komentarze Javadoc są zazwyczaj przeznaczone dla użytkowników interfejsu API. Są to również programiści, ale nie dbają o wewnętrzną strukturę systemu, tylko klasy, metody, dane wejściowe i wyniki systemu. Kod jest zawarty w czarnej skrzynce. Te komentarze powinny być wykorzystane do wyjaśnienia, jak wykonać określone zadania, jakie są oczekiwane wyniki operacji, kiedy zgłaszane są wyjątki i co oznaczają wartości wejściowe. Biorąc pod uwagę zestaw dokumentacji wygenerowany przez Javadoc, powinienem być w stanie w pełni zrozumieć, w jaki sposób korzystać z interfejsów, bez patrzenia na wiersz kodu.

Thomas Owens
źródło
+1, to dobra rozmowa. Myślę, że moim głównym problemem jest to, że nie widzę w nim dwóch różnych docelowych odbiorców, ale masz rację.
Andreas Johansson
1
@Andiaz - Uważam, że warto rozróżniać zewnętrzne krawędzie systemu (takie jak interfejs API usługi) i klasy w nim zawarte. Często pracuję nad projektami, w których konwencja polega na javadocu wszystkich metod publicznych, ale dużo bardziej dbam o klasy zewnętrzne, aby dać pewne wskazówki, w jaki sposób należy użyć klasę (i system). Zakładam, że w klasach wewnętrznych czytelnik ma większą wiedzę o domenach i minimalizuje javadoc, pozwalając, by nazwy metod mówiły same za siebie.
Steve Jackson
3
@ SteveJackson Zgadzam się, jednak znalazłem się przy użyciu większej liczby Javadoców (nawet w przypadku członków prywatnych), ponieważ IDE (przynajmniej Eclipse i NetBeans) wyświetlają komentarze Javadoc w etykietach narzędzi do uzupełniania kodu. Oczywiście nie są tak czyste, jak interfejsy publiczne, dostarczają wskazówek / notatek innym programistom.
Thomas Owens
24

Kod mówi jak . Komentarze mówią dlaczego , a może nawet dlaczego nie .

Twoim zadaniem jest zapewnienie zarówno przyszłym czytelnikom, jak i opiekunom twojego kodu. Umieść wszystko, co możesz w kodzie, a resztę w komentarzach.

Pamiętaj, że najtrudniejsze do uchwycenia są decyzje projektowe - pamiętaj o nich.


źródło
2
+1: To nie jest „albo” albo w wyłącznym sensie. Wszystko to w sensie integracyjnym.
S.Lott
Zdecydowanie się na to zgadzam. Czy jest jeszcze coś, co należy rozważyć, szczególnie jeśli chodzi o javadocs? Mogę sobie wyobrazić, że opisanie, co robi metoda, może być przydatne np. W przypadku interfejsów API.
Andreas Johansson
Javadocs są bardzo łatwo dostępne z większości IDE. Ułatw nawigację do dalszych informacji.
+1: Najlepsze komentarze, jakie widziałem, zawierały odniesienia do artykułów, w których zastosowane algorytmy zostały szczegółowo omówione; nie jest to coś, co można samodzielnie udokumentować w nazwach zmiennych / metod i niekoniecznie należy do komentarzy-komentarzy, ponieważ algorytm jest częścią implementacji, a nie interfejsu .
Donal Fellows
4

Korzystanie z Javadocs nie robi prawdziwej różnicy - ponieważ wygenerowane dokumenty zawierają nazwę twoich funkcji wraz z tekstem z komentarzy, absolutnie nie ma powodu, dla którego powinieneś powtarzać cokolwiek w komentarzach, które wynika z samej nazwy funkcji.

Z drugiej strony, jeśli masz funkcję, w której należy najpierw spojrzeć na implementację, aby zrozumieć, do czego jest ona dobra (a tym samym nie udostępnia tych informacji Javadocs), to kod IMHO nie jest samodokumentujący, bez względu na to, jak jasne jest wdrożenie.

Doktor Brown
źródło
3
+1 moim ulubionym jest, gdy standard kodu firmy wymaga udokumentowanych metod, ale każdy korzysta z generatora, który po prostu powtarza to, co już kod mówi. Nużący i bezużyteczny.
Kryptic
1

Myślę, że w javadocs wszystko jest takie samo, jak w przypadku jakiejkolwiek dokumentacji - główna zasada brzmi:

podążaj za publicznością

Czy wiele osób czyta twoje javadocs? Jeśli tak, warto zainwestować wysiłki w jego prawidłowe działanie.

Czy twoi czytelnicy zwykle pomijają czytanie kodu na rzecz studiowania javadocs? Jeśli tak, warto dwa razy więcej wysiłku poświęcić na dobre napisanie.

  • Dokładnie tak jest w przypadku dokumentacji JDK . Zgadnij, że Sun / Oracle włożyło w to wiele wysiłku i wydaje się, że mają dobrą zwrot w dokumentach API często używanych przez społeczność.

Czy to twoja sprawa? Jeśli nie, zastanów się dwa razy, czy wysiłki włożone w javadocs są uzasadnione.

Jak już wspomniano powyżej, słuchaj widowni, aby znaleźć drogę.

  • Jeśli usłyszysz aktywne skargi dotyczące niewystarczającej dokumentacji, rozważ inwestowanie w jej ulepszanie.
     
    Z drugiej strony, jeśli wszystko, co słyszysz, to programiści narzekający na zasady braindead, zmuszające ich do marnowania czasu na bezużyteczne pisanie, to są duże szanse, że twoje wysiłki javadocs są jak inwestowanie w kredyty hipoteczne subprime . Zamiast tego pomyśl o lepszych inwestycjach.
komar
źródło
0

Chcę tylko skomentować obawę, że komentarze Javadoc mogą stać się nieaktualne. Podczas gdy @JonathanMerlet ma rację mówiąc, że Javadoc powinien być stabilny, możesz również pomóc, przeglądając Javadoc i komentarze oraz kod podczas recenzji. Czy komentarze są zgodne z tym, co robi kod? Jeśli nie, co jest niepoprawne i nalegaj, aby programista go naprawił. Spróbuj zachęcić innych programistów do zrobienia tego samego. Pomaga to aktualizować nie tylko zewnętrzną dokumentację (komentarze Javadoc), ale także wszelkie regularne komentarze do kodu. Pomaga to programistom, którzy przyjdą po refaktoryzacji, szybciej i łatwiej zrozumieć kod, a także ułatwia jego utrzymanie w przyszłości.

Eric Hydrick
źródło
-1

Myślę, że javadocs jest odpowiedni dla części, które powinny pozostać stabilne (API), aby zminimalizować ryzyko przedawnienia komentarzy, podczas gdy kod samodokumentujący jest świetny dla tego, co podlega częstej zmianie (implementacji). Oczywiście interfejsy API mogą się zmieniać w trakcie projektu, ale mając nagłówek tuż przed deklaracją, synchronizacja obu nie jest trudna (w porównaniu z komentarzami do wielu wierszy wyjaśniającymi kilka wierszy kodu)

Jonathan Merlet
źródło