Najlepsze praktyki pisania komentarzy i dokumentacji

20

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ć?”

jayunit100
źródło

Odpowiedzi:

40
  • 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.

maniak zapadkowy
źródło
6
komentarze powinny również powiedzieć, dlaczego nie robisz tego w inny sposób - tj. ważne wybory projektowe - ponieważ przyszli opiekunowie nie uzyskaliby tych informacji w inny sposób.
2
Sądzę, że wiele razy komentarz powinien powiedzieć, CO robisz. Pomysł, że tylko komentarze „dlaczego” są moim zdaniem anty-wzorem. Mitem jest, że możesz napisać cały kod na tyle jasno, że każdy programista może go zrozumieć na pierwszy rzut oka, a moje doświadczenie to większość programistów, którzy myślą, że piszą czysty kod, ale nie. To tak samo, jak powiedzenie: „Nie muszę nazywać tej funkcji opisowo, ponieważ każdy może po prostu odczytać kod w funkcji, aby zobaczyć, co robi”. - to też nie ma sensu, prawda?
dallin
2
@dallin, jeśli kod nie jest jasny o tym, co robi; rozważ refaktoryzację. w przeciwnym razie dodaj komentarz wyjaśniający, dlaczego jest tak zaimplementowany (co zdarza się również, aby wyjaśnić, jak lepiej). Porównanie z nazwami opisowymi to jabłka / pomarańcze, nazwa opisowa wyjaśnia, gdzie używana jest funkcja , i możesz nie mieć dostępu do kodu źródłowego funkcji.
maniak zapadkowy
@dallin: „To mit, że można napisać cały kod na tyle jasno, że każdy programista może to zrozumieć na pierwszy rzut oka”, wujek Bob chciałby z tobą porozmawiać. - „Nie muszę nazywać tej funkcji opisowo, ponieważ każdy może po prostu odczytać kod w funkcji, aby zobaczyć, co robi”. Nadawanie dobrych i jasnych nazw zmiennych i metod jest dokładnie tak, jak programiści powinni wyjaśnić, jaki jest ich kod to robi!
klaar
14

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.

Dawood mówi, że przywraca Monikę
źródło
1
To dobry początek, ale myślę, że aby odpowiedzieć na pytanie OP, musisz napisać coś, co rozwiąże jego rzeczywiste obawy związane z automatyczną weryfikacją.
Robert Harvey
2
+1 - Uważam również, że komentarze powinny służyć wyłącznie do wyjaśnienia, dlaczego napisano kod. Wiem, co if (a == b) then c();robi, ale jeśli nie wiem, dlaczego tak się dzieje - wtedy należy użyć komentarza :)
Deco
Deco - całkowicie się zgadzam. Komentarze są dobre, gdy chcę zrozumieć, jak dana metoda pasuje do całego procesu. Innymi słowy, DLACZEGO nazwałbyś tę metodę lub DLACZEGO robi to, co robi.
Dawood mówi, że przywróć Monikę
Oprócz tego, aby napisany kod był jasny, powinniśmy również zachować (na poziomie kodu) pomysły, przemyślenia itp. Za pomocą komentarzy TODO. Na przykład, jeśli widzisz, że funkcja / klasa jest w stanie poprawnie obsłużyć bieżący rozmiar danych, ale potencjalnie nie poradzi sobie z obciążeniem po 2 latach, to pamiętaj, aby napisać tam swoją obserwację za pomocą komentarza TODO. Przyszli programiści naprawdę docenią twoje starania. Nigdy nie próbuj zanotować tych rzeczy w osobnym dokumencie tekstowym / tekstowym, podczas pisania kodu nikt tak naprawdę nie odwołuje się do takich dokumentów.
TechCoze
patrz także: „Komentarze to zapach kodu”
komik
5

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).

Josh Smeaton
źródło
1
Sphinx porównuje kod z dokumentacją w celu zapewnienia wskaźników zasięgu.
S.Lott,
3

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.

Dipan Mehta
źródło
1
Nie zgadzam się z ostatnim zdaniem tutaj. Właśnie skończyłem kontrakt, pracując pod kierownictwem zespołu, który przedstawił bardzo szczegółowe recenzje. Jego recenzje zawsze zawierały komentarze - jak zostały sformułowane, czy nazwy zmiennych są poprawne, czy zawierają wszystkie informacje, które przyszły programista może chcieć poznać. Wkrótce wiedziałem, czego się spodziewał w każdym komentarzu, i byłem w stanie przedstawić komentarze do jego standardu. Tak więc, pod warunkiem, że zasady organizacyjne zawierają recenzje kodu i uwzględniają komentarze w przeglądzie kodu, tak się stanie.
Dawood mówi, że przywróć Monikę
Zazwyczaj jest to jedyny rodzaj komentarza, który piszę, zwłaszcza w przypadku metod dokumentowania tego, co wchodzi i co z niego wychodzi (pracuję z luźno napisanymi językami).
DanMan
2

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.

Doktor Brown
źródło
+1 za kod ukończony. Clean Code autorstwa Roberta Martina zawiera również dobry rozdział na temat pisania użytecznych pochwał. Nie jestem pewien co do świata Java, ale w świecie .NET mamy Resharper, który może „automagicznie” sprawdzać odwołania do elementów kodu w komentarzach :)
MattDavey
0

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 .

EGHM
źródło