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?
źródło
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
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.
źródło
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.
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ę.
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.
źródło
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.
źródło
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)
źródło