Najlepsze praktyki pisania komentarzy i dokumentacji

Komentowanie jest dziś łatwiejsze niż kiedykolwiek. W Javie istnieje kilka fajnych technik łączenia komentarzy z klasami, a środowiska IDE Java są dobre w tworzeniu powłok komentarzy. Języki takie jak Clojure pozwalają nawet dodać opis funkcji w samym kodzie funkcji jako argument.

Jednak wciąż żyjemy w czasach, w których często są nieaktualne lub kiepskie komentarze dobrych programistów - jestem zainteresowany poprawieniem niezawodności i użyteczności moich komentarzy.

Szczególnie interesuje mnie Java / Clojure / Python, ale odpowiedzi nie muszą być specyficzne dla języka.

Czy istnieją jakieś nowe techniki, które sprawdzają poprawność komentarzy i automatycznie wykrywają albo „wątłe” komentarze (na przykład komentarze z magicznymi liczbami, niepełne zdania itp.), Albo niepoprawne komentarze (na przykład wykrywanie niepoprawnych zmiennych lub tym podobne).

I co ważniejsze: czy są tam akceptowane „zasady komentowania” lub strategie? Istnieje wiele porad na temat kodowania - ale co z „jak komentować?”

• Nazwy / dokumentacja powinny informować o tym , co robisz.

• Wdrożenie powinno powiedzieć ci, jak to robisz.

• Komentarze powinny wyjaśniać , dlaczego robisz to tak, jak robisz.

Może to być kontrowersyjne, ale radzę napisać jak najmniej komentarzy. Zamiast tego używaj ładnych, wyraźnych nazw klas, nazw zmiennych i nazw metod. Napisz swój kod w najczystszy możliwy sposób; i uważaj to za najważniejszy atrybut twojego kodu (poza tym, że spełnia on swoje wymagania). Napisz komentarz tylko wtedy, gdy podałeś metodę tak klarowną, jak to tylko możliwe, a nadal uważasz, że wymaga ona dalszego wyjaśnienia.

I stosuj praktykę organizacyjną, że za każdym razem, gdy ktoś w jakikolwiek sposób zmienia klasę, musi upewnić się, że wszystkie komentarze są poprawne.

Nie jestem pewien co do innych języków, ale Python umożliwia pisanie doctestów, które są formą samo-sprawdzających się komentarzy. Oczywiście nie należy ich używać zamiast prawdziwych testów jednostkowych, ale są one szybką i łatwą metodą dokumentowania określonych funkcji, które mogą nie być tak oczywiste, jak powinny. Dodatkową zaletą jest możliwość wykonywania testów komentarzy w celu sprawdzenia, czy komentarze są nadal poprawne (przynajmniej część z nich zawiera testy).

Jednym z najbardziej autorytatywnych miejsc, w których można znaleźć komentarz do kodu w celu automatycznego generowania dokumentacji, jest z pewnością doxygen . Chociaż mogłoby być więcej takich narzędzi.

Określa to standard pisania komentarzy, których należy przestrzegać w celu automatycznego generowania dokumentacji. Daje to jednak więcej struktury, ale nie sprawdza poprawności semantycznej; na przykład nie może sprawdzić, czy użyłeś mylącego angielskiego do opisania celu funkcji!

Chociaż jest to najlepsza rzecz, która nadaje strukturę komentarzom, osobiście uważam, że potrzebna jest większa dokumentacja, aby kod był łatwiejszy w utrzymaniu. Jakiś czas temu w P.SE pojawiło się pytanie. Czy kod może być dokumentacją narzędzi programistycznych typu open source? Jak często to jest Oczywiście dotyczy to również projektów innych niż open source.

Aby kod był łatwiejszy w utrzymaniu - jest praktycznie ważniejsze, aby istniała zewnętrzna dokumentacja, która pomaga stworzyć strukturę sposobu traktowania kodu, a następnie komentarze wewnątrz kodu powinny być ograniczone, aby zobaczyć

Myślę, że jeśli chcesz zdefiniować zasady pisania komentarzy , powinieneś uwzględnić je jako holistyczne podejście zawarte w standardzie kodowania. Zobacz: Jakie mogą być pułapki we wprowadzaniu przewodnika po stylu i oprogramowania do generowania dokumentacji w zespole programistów?

Zazwyczaj komentarze stanowią mniej niż 5% kodu. W praktyce, podczas gdy same recenzje kodu zwracają znacznie mniej uwagi (w porównaniu z innymi aspektami rozwoju), jest praktycznie trudne, aby komentarze były również przeglądane.

Czy istnieją jakieś nowe techniki, które sprawdzają poprawność komentarzy i automatycznie wykrywają albo „wątłe” komentarze (na przykład komentarze z magicznymi liczbami, niepełne zdania itp.), Albo niepoprawne komentarze (na przykład wykrywanie niepoprawnych zmiennych lub tym podobne).

Istnieje dobrze znana technika - nazywa się to „przeglądem kodu” i ma siostrę o imieniu „programowanie par”. Nie oczekuj tutaj niczego „automagicznie”.

I co ważniejsze: czy są tam akceptowane „zasady komentowania” lub strategie? Istnieje wiele porad na temat kodowania --- ale co z „jak komentować?”

„Kod zakończony” zawiera nie tylko wszystko o tym, jak napisać kod, ale także rozdziały na temat „jak komentować”, a zwłaszcza na temat pisania kodu samokontrującego.

Jednym ze źródeł, które podobały mi się w Javie, jest Oracle Jak pisać komentarze do dokumentu dla narzędzia Javadoc :

Ten dokument opisuje przewodnik po stylach, konwencje znaczników i obrazów, których używamy w komentarzach do dokumentacji programów Java napisanych w Java Software, Sun Microsystems.

I pozycja 44: Napisz komentarze do dokumentu dla wszystkich odsłoniętych elementów API :

Jeśli interfejs API ma być użyteczny, musi zostać udokumentowany. Tradycyjnie dokumentacja API była generowana ręcznie, a utrzymywanie jej w synchronizacji z kodem było uciążliwe. Środowisko programowania Java ułatwia to zadanie dzięki narzędziu Javadoc. Javadoc generuje dokumentację API automatycznie na podstawie kodu źródłowego ze specjalnie sformatowanymi komentarzami do dokumentacji, bardziej znanymi jako komentarze do dokumentów.

z Effective Java 2nd Edition .