Kod samodokumentujący vs Javadocs?

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?

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.

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.

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.

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.

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.

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)