Przewodnik dla początkujących po pisaniu komentarzy?

27

Czy istnieje ostateczny przewodnik po pisaniu komentarzy do kodu, skierowany do początkujących programistów?

Idealnie obejmowałoby to, kiedy komentarze powinny (i nie powinny) być używane oraz jakie komentarze powinny zawierać.

Ta odpowiedź :

Nie komentuj CO robisz, ale DLACZEGO to robisz.

O CO zadba czysty, czytelny i prosty kod z odpowiednim wyborem nazw zmiennych do jego obsługi. Komentarze pokazują strukturę wyższego poziomu w kodzie, której sam kod nie może (lub jest trudny) pokazać.

zbliża się, ale jest to trochę zwięzłe dla niedoświadczonych programistów (myślę, że to rozszerzenie z kilkoma przykładami i przypadkami narożnymi byłoby doskonałe).

Aktualizacja : Oprócz odpowiedzi tutaj, uważam, że ta odpowiedź na inne pytanie jest bardzo istotna.

language-agnostic comments Cameron
źródło
Myślę, że szybko przenosimy się do świata, w którym ludzie już nie komentują. Na lepsze (bardziej prawdopodobne) na gorsze. Zwinny.
MK01
1
@MK: Jeśli tak jest (zazwyczaj zgadzam się z tą odpowiedzią ), równie przydatny byłby przewodnik wyjaśniający, jak nie pisać komentarzy i dlaczego należy ich unikać. W rzeczywistości im więcej różnych punktów widzenia, tym lepiej.
Cameron
Myślę, że małe komentarze w celu poprawy szybkości odczytu kodu są bardzo pomocne i zawsze będą. Nie kupuję w pełni rozumowania „nieaktualny komentarz”, nawet jeśli są one nieaktualne, miałyby wartość historyczną. Kiedyś pracowałem na bazie kodu, która czasami zawierała szczegółowe komentarze tu i tam i nigdy nie byłam naprawdę przygryziona tym, że komentarz był nieaktualny.
MK01
patrz także: „Komentarze to zapach kodu”
komik

Odpowiedzi:

38

Powinieneś zdawać sobie sprawę z największej słabości komentarzy: stają się one nieaktualne. Oznacza to, że wraz ze zmianami kodu programiści rzadko aktualizują komentarze, aby zachować synchronizację z kodem. Oznacza to, że nigdy nie można im ufać i nadal czyta się kod. Z tego właśnie powodu twój kod powinien być samodokumentujący. Powinieneś wybierać nazwy funkcji i zmiennych w taki sposób, aby kod brzmiał jak proza.

Więc nie dokumentuj, co robi kod. Zadbaj o to samodokumentujący się kod. Dokument DLACZEGO to robisz. DLACZEGO są zwykle związane z regułami biznesowymi lub architekturą i nie będą się często zmieniać i zestarzeją tak szybko w WHAT. Skrzynie na dokumenty. Wyjątki od dokumentów. Decyzje dotyczące projektu dokumentu. I co najważniejsze, udokumentuj te decyzje projektowe, które wziąłeś pod uwagę, ale zdecydowałeś się ich nie wdrażać (i udokumentuj DLACZEGO zdecydowałeś się ich nie używać).


źródło
2
Ostatni jest bardzo ważny. Czasami pojawia się błąd / efekt uboczny przy wdrażaniu oczywistego rozwiązania. Udokumentowanie, dlaczego zdecydowałeś się na inne rozwiązanie, zapobiega ponownemu wprowadzeniu błędu przez kolejnego programistę, gdy „naprawi” on pozornie słabe rozwiązanie.
CaffGeek
2
Kolejna kwestia: moja pierwsza praca uważała komentarze za równie ważne jak kod. Postaraj się przyzwyczaić do czytania komentarzy i kodu podczas recenzowania i staraj się nalegać, aby komentarze były zawsze aktualne. Pomaga to uniknąć nieaktualnych komentarzy i aktualizuje reguły biznesowe itp. W kodzie.
Eric Hydrick,
10

Powinieneś przeczytać książkę Czystego kodu Roberta C. Martina . To ładnie wyjaśnia, że ​​jeśli potrzebujesz komentarzy, najprawdopodobniej nie kodujesz poprawnie. Najlepiej byłoby, gdyby kod był „komentujący”. Książka Clean Coder wyjaśnia, jak to zrobić, aby komentarze nie były konieczne, i dobrze opisała, jak robić komentarze w sytuacjach, w których jest to konieczne. (Na przykład wyjaśnienie złożonej formuły matematycznej)

Kok
źródło
Chociaż nie chciałbym tak bardzo wyjaśniać złożonej formuły matematycznej, jak chciałbym, aby była napisana we właściwej notacji matematycznej (prawdopodobnie TeX), z wyjaśnieniem jej znaczenia i źródła. Jeśli nie rozumiesz tej formuły, to nie powinieneś zadzierać z kodem, który używa jej do obliczenia pewnej wartości, ponieważ wyjątkowo prawdopodobne jest, że spieprzysz i wprowadzisz (subtelne lub nie) błędy.
CVn
Kod może tylko powiedzieć jak , a nie dlaczego i dlaczego nie . Potrzebujesz do tego komentarzy.
7

Jak wspomniano, kod Complete ma różne wytyczne dotyczące pisania komentarzy. Krótko mówiąc, jest to PDL i można je podsumować jako:

  1. Opisz swoje zamiary, a nie to, co robi kod. Unikaj opisywania szczegółów implementacji, chyba że używasz sztuczki lub implementacji niestandardowych. Na przykład, użycie bitów przesuwających do podziału, użycie arytmetyki wskaźnika w celu uzyskania dostępu do członków klasy lub użycie niestandardowego przydziału pamięci dla niektórych obiektów w puli.

  2. Najpierw napisz pseudo kod (tj. Komentarze), a następnie napisz prawdziwy kod po zakończeniu opisu procedury / metody / funkcji. Używany język jest wysoki, ale specyficzny, więc może być dość gadatliwy

  3. Pomyśl o tym, co robi Twój kod, jeszcze przed jego napisaniem

  4. Komentarze powinny być tak zbliżone do rzeczywistego kodu

Celem jest uniknięcie długich, niepowiązanych komentarzy, które mogą być nieaktualne, ale posiadanie komentarzy odzwierciedlających zamiar i cel kodu. Korzystanie z pseudo kodu wysokiego poziomu pomaga również wyjaśnić swoje myślenie przed napisaniem implementacji.

Na GameDev.net [link wyjaśnia PDL] [1] znajduje się link, na wypadek gdybyś nie chciał wyśledzić książki.

Extrakun
źródło
5
Najpierw napisz pseudo kod (tj. Komentarze) . Nie mogłem się nie zgodzić. Nie ma lepszego sposobu, aby zapewnić, że komentarze nie będą pasować do kodu. Nowi koderzy (a pytający specjalnie proszony o przewodnik dla początkujących) zhakują i refaktoryzują funkcje sto razy, zanim będą z nich zadowoleni, kod zostanie szybko przeniesiony, przepisany, przepisany, a na koniec mogą mają eleganckie działające rozwiązanie, ale nie będzie przypominało ich początkowego pseudokodu. Czy komentarze zostaną przeniesione i zaktualizowane, gdy uruchomią kod? Możesz się założyć, że nie będą. Moje dwa centy.
Binary Worrier
1
Komentarze pseudo kodu podpowiedzą również, co powinien zrobić kod. Kod powinien ci to powiedzieć. Pseudo kod nie powie ci, dlaczego kod to robi. -1 stary, przepraszam, ale nie mogę się zgodzić z drugim punktem, czasy się zmieniły.
Binary Worrier
1
Nie kłócić się, ale raczej wyjaśnienia - pseudo kod ma wyjaśnić cel napisanego kodu. Oznacza to, że komentarz nie dotyczy szczegółów implementacji (takich jak „Dodaj x do góry stosu”), ale raczej tego, co powinien zrobić kod (np. „Spraw, aby okno wyświetlało się przed wszystkim innym”). Jak słusznie zauważyłeś, musisz przenosić komentarze za pomocą kodu. Nie zgadzam się z tym, że kod może ci powiedzieć, co robi kod - cały czas. Nawet jeśli pomocny / dokładny komentarz (jeśli uda mi się go dobrze napisać!) Przechodzi długą drogę. W końcu wciąż IMHO.
Extrakun,
3
Wywołana metoda lub funkcja showWindowOnTop(window)zawsze będzie lepsza niż komentarz tego samego rodzaju, wszystko to jest przestarzałe i zła rada w 2012 r. 1) Nazwy funkcji / metod opisują zamiar, 2) pseudokod jest pustym ćwiczeniem z nowoczesnymi łańcuchami narzędzi 3) Testy mówią ci, co powinien zrobić kod, zanim go napiszesz, 4) dobrze nazwany kod jest lepszy niż komentarze, które nie pasują do źle nazwanego kodu
1

Moją sugestią byłoby napisanie kodu bez żadnych komentarzy, a następnie odejście od niego. Wróć za rok i przeczytaj. Część, której nie rozumiesz łatwo, to część, którą powinieneś skomentować.

Kevin
źródło
1
Hah, tak ;-) Nie jest to jednak szczególnie przydatna rada - być może powinien to być komentarz?
Cameron
część, której nie rozumiesz, powinieneś napisać w mniejszych, lepiej nazwanych częściach. Głównym powodem, dla którego komentarze są umieszczane w kodzie, jest to, że funkcje / metody są zbyt długie i powinny składać się z wielu mniejszych kawałków samodokumentujących.
0

Bardzo podoba mi się, jak Evan Todd podsumowuje swoje zdanie na temat jedynych użytecznych kategorii komentarzy ( cytowanie z jego bloga ):

  • Komentarze wyjaśniające dlaczego, a nie co. Te są najbardziej przydatne.
  • Komentarze z kilkoma słowami wyjaśniającymi, co robi poniższy gigantyczny fragment kodu. Są one przydatne do nawigacji i czytania.
  • Komentarze w deklaracji struktury danych, wyjaśniające, co oznacza każde pole. Często są one niepotrzebne, ale czasami intuicyjne mapowanie koncepcji do pamięci jest niemożliwe, a do opisania map konieczne są komentarze.
Cameron
źródło