Standard kodowania dla przejrzystości: skomentować każdą linię kodu?

Pracowałem w sklepach, które produkują oprogramowanie krytyczne dla życia i zajmowałem się regułami komentowania, które miały na celu utrzymanie czytelności kodu i potencjalne uratowanie życia. Z mojego doświadczenia wynika jednak, że wymóg ten staje się umysłem, od którego należy usunąć listę kontrolną i nie pomaga mi skupić się na pisaniu zrozumiałego kodu. Odwraca to także moją recenzenta od bardziej znaczącej rozmowy ze mną na temat tego, jak ułatwić zrozumienie kodu.

Oceniłem również kod ucznia, który nie zawiera komentarzy i zrozumiałem, dlaczego należy go oznaczyć za zaniedbanie go.

Rozumiem, że używanie dobrych nazw, utrzymywanie prostych struktur, krótkich funkcji i koncentracji modułów sprawi, że kod będzie wystarczająco zrozumiały, aby komentarze można było zminimalizować.

Rozumiem również, że komentarze powinny wyjaśniać, dlaczego kod robi to, co robi, a nie jak.

Biorąc to wszystko pod uwagę, czy w ogóle można napisać dobre standardy kodowania, które wychwytują ten pomysł? Te, które będą istotne w recenzowaniu, ale nie zmienią się w bezmyślną listę kontrolną, która generuje notatki nie bardziej pomocne niż: „Zapomniałeś skomentować w linii 42”.

Przykład rodzaju kodu, którego może wymagać ta reguła, gdy jest traktowany jako wiersz na liście kontrolnej:

/* Display an error message */
function display_error_message( $error_message )
{
    /* Display the error message */
    echo $error_message;

    /* Exit the application */
    exit();
}

/* -------------------------------------------------------------------- */

/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
    /* Display an error message */
    display_error_message( 'Error: Configuration file not found. Application has stopped');
}

Jeśli jest to możliwe, aby wyrazić to poprawnie w dokumencie standardowym, a może po prostu nie być, chciałbym uchwycić pomysł w następujący sposób:

Rozważ komentarz dla każdej linii, sekwencji, instrukcji, sekcji, struktury, funkcji, metody, klasy, pakietu, komponentu ... kodu. Następnie rozważ zmianę nazwy i uproszczenie, aby wyeliminować potrzebę tego komentarza, aby móc go usunąć. Zamelduj się, dopóki komentarze są rzadkie. Powtarzaj do terminu. Następnie powtórz trochę więcej

Odpowiedź Michaela Durranta jest IMHO niezła, ale nie jest dosłownie odpowiedzią na pytanie (jak sam przyznał), więc postaram się udzielić odpowiedzi, która:

Rozumiem również, że komentarze powinny wyjaśniać, dlaczego kod robi to, co robi, a nie jak.

Biorąc to wszystko pod uwagę, czy w ogóle można napisać dobre standardy kodowania, które wychwytują ten pomysł?

Oczywiście możesz napisać listę kontrolną do recenzji kodu , zawierającą pytania takie jak

• „jeśli jest komentarz, czy wyjaśnia, dlaczego kod robi to, co robi?”
• "czy każdy wiersz kodu - w swoim kontekście - jest wystarczająco oczywisty, aby nie wymagał komentarza, lub jeśli nie, czy towarzyszy mu komentarz, który zamyka tę lukę? Lub (najlepiej) czy kod można zmienić, aby nie potrzebuje już komentarza? ”

Jeśli chcesz, możesz nazwać to „standardem kodowania” (lub nie, jeśli uważasz, że termin standard kodowania powinien być zarezerwowany dla listy reguł braindead, łatwo odpowiedzieć, jeśli są spełnione, czy nie, w jaki sposób formatowanie kodu powinien wyglądać lub gdzie zadeklarować zmienne). Nikt nie przeszkadza ci skoncentrować się na liście kontrolnej na pytaniach semantycznych , zamiast iść łatwą drogą i wprowadzać do niej tylko formalne reguły.

Pod koniec dnia upewnij się, że Twój zespół potrzebuje takiej listy kontrolnej. Aby zastosować takie pytania, potrzebujesz programistów z pewnym doświadczeniem jako recenzenci i musisz dowiedzieć się, czy naprawdę poprawi to czytelność kodu w zespole ekspertów. Ale to jest coś, co musisz wypracować razem ze swoim zespołem.

Główne anty-wzorce prowadzące do niskiej jakości kodu o mniejszej przejrzystości

btw czytelnicy, tytuł był pierwotnie „komentować każdą linię kodu?” i możecie sobie wyobrazić instynktowną reakcję wielu z nas, w tym mnie. Później wróciłem do bardziej dokładnego tytułu.

Na początku, czytając twoje pytanie, pomyślałem, że w komentarzach powielasz wiele rzeczy, ale ok, może, jeśli masz wystarczającą liczbę recenzji w recenzjach wielu osób ... ale potem znowu: ludzie popełniają błędy, nie zauważają niespójności itp. Z czasem w końcu będą różnice. Po zastanowieniu myślę, że problem jest znacznie większy:

Programiści będą mieli tendencję do pisania gorszego kodu. Będą używać bardziej tajemniczych nazw i struktur, ponieważ „wyjaśniono to w komentarzu - patrz!”.

Rozważać:

living_room_set = tables + chairs.

Teraz rozważ:

set = tbls+chrs # Make the set equal to the table plus the chairs

Masz nie tylko więcej tajemniczych nazw, ale też więcej do przeczytania, musisz także patrzeć w przód iw tył, patrzeć na kod, co to jest zestaw? spójrz w lewo na kod, spójrz w prawo na komentarze, czym są tbls, spójrz w lewo na kod, spójrz w prawo na komentarze, co to są chrs, spójrz w prawo na komentarz. Fuj!

Podsumowanie

Opracuj lub ulepsz standard komentowania, jeśli jesteś zmuszony do zajmowania obecnej pozycji jako programista (jako były program COBOL z pewnością widziałem duże!), Ale spędziłem tyle czasu, energii i pasji, walcząc przeciwko komentowaniu anty- wzorzec za pomocą argumentów:

• Kod i komentarze zsynchronizują się ze sobą, gdy tylko jeden zostanie zmieniony

• Komentarze mogą opisywać, co myśli jedna osoba, ale mogą być błędne, a tym samym zatuszować błędy

• Kod staje się trudniejszy do odczytania

• Dobry kod staje się trudniejszy do napisania

• Tendencja do używania bardziej tajemniczych nazw

• Nadmiar znaków do odczytania w kodzie i komentarzach

• Różni redaktorzy używają różnych stylów

• Wymaga wyższej znajomości języka angielskiego niż tylko kodowania

• Zajmuje czas i zasoby oraz odejmuje od wartości długoterminowej *

Plus argumentują za lepszym kodem bez takich komentarzy, - w rzeczywistości mają standardowy (!) - wszystkie nazwy zmiennych muszą być pełnymi_ angielskimi_słówkami - jest jeden! Wykorzystaj więc tę „standardową” energię w kierunku standardów dobrze napisanego kodu i testów.

Jednym z dwóch trudnych problemów jest nazywanie rzeczy - nie pomijaj problemu w komentarzach.

Biorąc pod uwagę, że jednym z innych problemów jest przedwczesna optymalizacja i ogólnie optymalizacja może prowadzić do niejasnego kodu „dlaczego w ten sposób”, jest to jeden z obszarów, w którym komentarze wyjaśniające do pozornie złego kodu mogą być korzystne, chociaż powyższe zastrzeżenia nadal mają zastosowanie.

* kod jutra

Nie sądzę, że dokument standardów kodowania jest miejscem, w którym można określić, co jest już zdrowy rozsądek. Celem standardu kodowania jest zagwarantowanie spójności (i unikanie argumentów) w kwestiach, w których rozsądni ludzie mogą się nie zgodzić i nie ma jednej oczywistej właściwej odpowiedzi, np. Konwencje nazewnictwa, wcięcia itp.

Komentowanie takie jak w twoim przykładzie jest obiektywnie bezużyteczne i może być spowodowane niedoświadczonym programistą lub programistą pracującym z systemem kompilacji, który mechanicznie sprawdza obecność komentarzy (naprawdę zły pomysł, ale istnieje). W obu przypadkach rozwiązaniem jest edukacja, prawdopodobnie poprzez przeglądy kodu.

Jeśli zaczniesz dodawać wszelkiego rodzaju „najlepsze praktyki” do standardu kodowania, skończysz na powtarzaniu tego, co jest już powiedziane w wielu książkach. Wystarczy kupić „Clean Code”, „Code Complete” i „The Pragmatic Programmer” danemu deweloperowi i zachować oszczędność standardu kodowania.

To niemożliwe. W zasadzie próbujesz zmechanizować właściwy osąd.

Pisząc krytyczne oprogramowanie, takie jak systemy medyczne podtrzymujące życie, ogromne ilości list kontrolnych i innych rzeczy są praktycznie nieuniknione. Nie tylko inteligentni ludzie popełniają błędy, wiele oprogramowania dla tych urządzeń jest pisane przez ludzi, którzy nie są zbyt dobrzy w swojej pracy, więc „system” musi być w stanie zabezpieczyć się przed niechlujną pracą, dzięki czemu jest bezpieczny koszt zbywalności.

Najlepszym rozwiązaniem jest pominięcie rygorystycznego standardu kodowania w celu komentowania i poprowadzenie zespołu przez przykład. Pokaż innym, jak wyglądają dobre komentarze, starając się stworzyć kod dobrej jakości, który jest odpowiednio komentowany. Zamiast próbować znaleźć najlepszy sposób na opisanie, w jaki sposób pisać komentarze (które same są najczęściej wywołaniem osądu), pokaż innym, co masz na myśli na co dzień, dzięki własnym recenzjom kodu. Gdy inni członkowie będą czytać Twój kod, będą postępować zgodnie z nim, jeśli uznają to za przydatne. A jeśli nie mogą, to żaden Standard nie pomógłby im pisać lepszych komentarzy na początek.

Aktualizacja

Moja odpowiedź w cytatach na podkreślenie:

Wierzę, że odpowiedź, która stwierdza, że ​​komentarze nie powinny być poruszane w Kodeksach, a następnie zawiera zestaw pytań obronnych, aby z tym walczyć, jest jedyną prawidłową odpowiedzią.

Problem polega na tym, że standard kodowania to po prostu standard . Niezwykle subiektywne pomysły nie powinny znajdować się w standardzie kodowania . Może to być przewodnik po najlepszych praktykach, ale nie można go użyć przeciwko programistom podczas recenzji kodu. Moim osobistym zdaniem standard kodowania powinien być jak najbardziej zautomatyzowany. Kody recenzji poświęcają tak dużo czasu na spieranie nazw, odstępów, tabulatorów, nawiasów, komentarzy itp. Itd., Kiedy WSZYSTKO można zautomatyzować. Nawet odpowiedź na temat tablesi chairsmoże być zautomatyzowana. LINT'ery pozwalają na tworzenie słowników, sprawdzanie wielkości liter według pojęcia (zmienna, funkcja, metoda, klasa itp.).

Nawet sprawdzanie JavaDoc może zostać zaimplementowane przez Robot LINT'er przed zaakceptowaniem żądania ściągnięcia. Wiele projektów Open Source robi dokładnie to samo. Przesyłasz żądanie ściągnięcia, kod jest zbudowany z pliku Travis-CI, w tym analizy statycznej, i musi przejść wszystkie standardy kodowania, które można obiektywnie wyrazić. Żaden człowiek nie mówi o tym, że „robi to niepoprawnie” lub nie „podaje wartości” z komentarzem lub niewłaściwy sposób nazywania zmiennych itp. Dyskusje te nie mają żadnej wartości i najlepiej pozostawić je robotowi zewnętrznemu, który może przejąć ciężar naszego kodowania emocjonalnego.

Aby faktycznie odpowiedzieć na pytanie, musielibyśmy odpowiedzieć na pytanie, jak napisać Standard, który opisuje, jak odpowiedzieć na następujące pytanie: Czy ten komentarz miał wartość? Standard kodowania nie może dyktować „wartości” komentarza. Dlatego konieczne jest, aby człowiek przejrzał tę listę kontrolną. Samo wspomnienie o komentarzach w standardzie kodowania tworzy listę kontrolną, której oryginalny plakat chce uniknąć.

Dlatego komentarze zwykle nie są przetwarzane przez kompilator i usuwane. Ich wartości nie można ustalić. Czy dany komentarz jest cenny; Tak lub nie?. Odpowiedź na to pytanie jest trudna. Tylko ludzie mają szansę na prawidłowe udzielenie odpowiedzi, a nawet wtedy na odpowiedź może odpowiedzieć tylko osoba czytająca; gdzie na wartość tego komentarza ma wpływ pogoda, jego życie domowe, ostatnie spotkanie, w którym uczestniczyli i nie zakończyło się dobrze, pora dnia, ilość wypitej kawy. Ufam, że obraz staje się bardziej wyraźny.

Jak można to właściwie wyrazić w dowolnym standardzie? Standard nie jest użyteczny, chyba że można go stosować konsekwentnie i rzetelnie, a uczciwość polega bardziej na obiektywności niż na emocjach.

Sprzeciwiam się, że standard kodowania powinien pozostać jak najbardziej obiektywny. Sposób, w jaki zmienne są nazywane celami IS. Można je łatwo sprawdzić w słowniku pod kątem poprawnej pisowni, struktury gramatycznej i wielkości liter. Wszystko poza tym to „pissing match”, który wygrywa osoba o największej mocy lub „bicie brwi”. Coś, z czym osobiście walczę, by NIE robić.

Kiedy komentuję, zawsze komentuję rozmowę z moim przyszłym sobą w trzeciej osobie. Jeśli wrócę do tego kodu za 5 lat, co powinienem wiedzieć? Co byłoby pomocne, co byłoby mylące, a co nieaktualne z kodem? Istnieje inna różnica między dokumentowaniem kodu w celu wygenerowania publicznego API z możliwością przeszukiwania a kodem komentującym, który zapewnia wartość nieznanej stronie trzeciej, nawet jeśli ta strona trzecia jest tobą.

Oto dobry test lakmusowy. Jeśli byłeś TYLKO tym w projekcie. Wiedziałeś, że będziesz jedynym w projekcie. Co będzie w twoim standardzie kodowania? Chcesz, aby Twój kod był czysty, zrozumiały i zrozumiały dla ciebie w przyszłości. Czy miałbyś ze sobą recenzję kodu, dlaczego nie umieściłeś komentarza w każdej linii? Czy sprawdziłbyś każdy komentarz, który utworzyłeś na 100 zarejestrowanych plikach? Jeśli nie, to po co zmuszać innych?

Uważam, że w tych dyskusjach brakuje czegoś, co stanowi, że Future You jest także deweloperem tego projektu. Pytając o wartość, jutro jesteś także osobą, która może czerpać wartość z komentarza. Więc rozmiar zespołu, moim zdaniem, nie ma znaczenia. Doświadczenie zespołowe nie ma znaczenia, zmienia się zbyt często.

Żadna ilość kodu komentarza, który to recenzuje, nie powstrzyma twórcy tempa przed awarią i zabiciem pacjenta. Kiedy mówisz o komentarzu, który wpływa na kod, mówisz teraz o kodzie, a nie o komentarzu. Jeśli wystarczy zabraknąć komentarza, aby kogoś zabić, w procesie tym pachnie jeszcze coś.

Rozwiązanie tego rodzaju rygorystycznego sposobu kodowania zostało już dostarczone jako metodologia pisania samego oprogramowania. I nie ma to nic wspólnego z komentarzami. Problem z komentarzami polega na tym, że NIE mają one wpływu na ostateczny sposób działania produktu. Najlepsze komentarze na świecie nie mogą uchronić oprogramowania przed awarią, gdy są wbudowane w generator tempa. Lub podczas pomiaru sygnałów elektrycznych za pomocą przenośnego EKG.

Mamy dwa rodzaje komentarzy:

Komentarze do odczytu maszynowego

Style komentarzy, takie jak Javadoc, JSDoc, Doxygen itp., To wszystkie sposoby komentowania publicznego interfejsu zapewnianego przez zestaw kodu. Z tego interfejsu może korzystać tylko jeden inny programista (własny kod dla zespołu dwuosobowego), nieznana liczba programistów (np. JMS) lub cały dział. Ten kod można odczytać w zautomatyzowanym procesie, który następnie daje inny sposób czytania tych komentarzy, np. HTML, PDF i tym podobne.

Ten typ komentarza jest łatwy do stworzenia standardu. Staje się obiektywnym procesem zapewniania, że ​​każda publicznie wywoływana metoda, funkcja, klasa zawiera wymagane komentarze. Nagłówki, parametry, opis i. el. Ma to na celu ułatwienie innym zespołom znalezienia i używania kodu.

Robię coś, co wygląda na szalone, ale tak naprawdę nie jest

Te komentarze są tutaj, aby pomóc innym zobaczyć, DLACZEGO ten kod został napisany w określony sposób. Być może w procesorach, na których działa kod, występuje błąd numeryczny, który zawsze zaokrągla w dół, jednak programiści zazwyczaj zajmują się kodem, który zaokrągla w górę. Dlatego komentujemy, aby upewnić się, że programista dotykający kodu rozumie, dlaczego obecny kontekst robi coś, co normalnie wydaje się nieracjonalne, ale w rzeczywistości zostało napisane w ten sposób celowo.

Ten typ kodu powoduje tyle problemów. Zazwyczaj nie jest to komentowane, a później zostaje znalezione przez nowego programistę i „naprawione”. W ten sposób wszystko psuje. Nawet wtedy komentarze są tylko po to, aby wyjaśnić DLACZEGO tak naprawdę nie zapobiegać uszkodzeniu czegokolwiek.

Na komentarze nie można się powoływać

Komentarze są ostatecznie bezużyteczne i nie można im ufać. Komentarze zwykle nie zmieniają sposobu działania programów. A jeśli tak, to twój proces powoduje więcej problemów, niż powinien. Komentarze są przemyśleniami i nigdy nie mogą być niczym innym jak. Najważniejszy jest kod, ponieważ wszystko to jest przetwarzane przez komputer.

Może to zabrzmi dziwnie, ale proszę o wyrozumiałość. Która z tych dwóch linii naprawdę ma znaczenie?

// We don't divide by 0 in order to stop crashes.

return 1 / n;

W tym przykładzie liczy się tylko to, że nie mamy pojęcia, co to jest „n”, nie ma żadnego sprawdzania, czy n wynosi 0 ORAZ nawet jeśli było, nic nie powstrzymuje programisty przed n = 0sprawdzeniem PO za 0. Tak więc komentarz jest bezużyteczny i nic zautomatyzowanego nigdy tego nie złapie. Żaden standard tego nie złapie. Komentarz, choć ładny (dla niektórych), nie ma wpływu na wynik produktu.

Rozwój oparty na testach

Co ma wpływ na produkt? Branże, w których napisany kod może dosłownie ocalić lub zabić kogoś, muszą zostać rygorystycznie sprawdzone. Odbywa się to poprzez recenzje kodu, recenzje kodu, testowanie, testowanie, recenzje kodu, testy jednostkowe, testy integracyjne, testy, testowanie, miesiące testowania, recenzje kodu i próby dla jednej osoby, inscenizacja, recenzje kodu, testowanie, a następnie może w końcu wchodzę do produkcji. Komentarze nie mają z tym nic wspólnego.

Wolę kod, który NIE ma komentarzy, miał specyfikację, miał testy jednostkowe, które zweryfikowały specyfikację, badania wyników uruchomienia kodu na urządzeniu produkcyjnym, a następnie dobrze udokumentowany kod, który nigdy nie był testowany, ani nie miał nic do porównania kod przeciwko.

Dokumentacja jest dobra, gdy próbujesz dowiedzieć się, DLACZEGO ktoś zrobił coś w określony sposób, jednak przez lata odkryłem, że dokumentacja jest zwykle używana do wyjaśnienia, dlaczego zrobiono coś „sprytnego”, kiedy tak naprawdę nie było potrzeby być napisanym w ten sposób.

Wniosek

Jeśli pracujesz w firmie, która WYMAGA skomentowania każdego wiersza, GWARANTUJĘ, że co najmniej dwóch inżynierów oprogramowania w projekcie napisało już program do automatycznego tworzenia dokumentów w Perl, Lisp lub Python, który określa ogólną koncepcję tego, co robi linia , a następnie dodaje komentarz powyżej tego wiersza. Ponieważ jest to możliwe, oznacza to, że komentarze są bezużyteczne. Znajdź inżynierów, którzy napisali te skrypty, aby automatycznie udokumentować kod i użyj ich jako dowodu na to, dlaczego „Komentarz do każdej linii” marnuje czas, nie ma żadnej wartości i potencjalnie szkodzi.

Nawiasem mówiąc, pomagałem bliskiemu przyjacielowi w zadaniu programistycznym. Jego nauczyciel ustanowił wymóg, aby każdy wiersz musiał być udokumentowany. Widzę więc, skąd wziąłby się ten proces myślowy. Po prostu zadaj sobie pytanie, co próbujesz zrobić i czy to jest właściwa rzecz? Następnie zadaj sobie pytanie; Czy jest jakiś sposób na „granie” w system za pomocą tego procesu? Jeśli tak, to czy naprawdę wnosi jakąkolwiek wartość? Nie można automatycznie napisać testów jednostkowych, które sprawdzają, czy kod spełnia określoną specyfikację, a jeśli mogłyby, to nie byłoby złe.

Jeśli urządzenie musi działać w określonych warunkach, ponieważ znajdzie się w człowieku, jedynym sposobem upewnienia się, że go nie zabije, są lata testowania, wzajemnej oceny, prób, a NIGDY NIGDY nie zmiany kodu. Właśnie dlatego NASA nadal korzysta z tak starego sprzętu i oprogramowania. Jeśli chodzi o życie lub śmierć, nie tylko „dokonaj niewielkiej zmiany i sprawdź ją”.

Komentarze nie mają nic wspólnego z ratowaniem życia. Komentarze są dla ludzi, ludzie popełniają błędy, nawet podczas pisania komentarzy. Nie ufaj ludziom. Ergo, nie ufaj komentarzom. Komentarze nie są twoim rozwiązaniem.

Istnieją dwie różne rzeczy, do których nawiązujesz, gdy mówisz o komentarzach. Nie są takie same, a rozróżnienie jest ważne.

Dokumentacja mówi o zewnętrznych fragmentach kodu - jego interfejsie.

Zazwyczaj oprzyrządowanie pozwala na ich odczytanie w sposób „samodzielny”, tzn. Nie patrzysz jednocześnie na kod bazowy.

Cały interfejs powinien zostać udokumentowany (np. Każda metoda, z wyłączeniem metod prywatnych) i powinien opisywać dane wejściowe, wyniki oraz wszelkie inne oczekiwania, ograniczenia itp., Zwłaszcza rzeczy, których nie można wyrazić za pomocą ograniczeń, testów itp. ( Dokładnie, ile szczegółów i gdzie idzie, zależy od projektu).

Dobra dokumentacja pozwala potencjalnemu konsumentowi zdecydować, czy, kiedy i jak korzystać z kodu.

Komentarze w kodzie źródłowym mają inny cel. Są tam dla osób przeglądających kod źródłowy. Opisują przede wszystkim wdrożenie.

Komentarze są zawsze wczytywane w kod źródłowy.

Komentarze powinny wyjaśniać zaskakujące decyzje lub złożone algorytmy lub opcje, które nie zostały podjęte (i uzasadnienie). Są tam, aby przyszli programiści mogli zrozumieć procesy myślowe swoich poprzedników i mieć pod ręką informacje, które w przeciwnym razie mogliby przeoczyć lub spędzać dużo czasu na poszukiwaniu, np.

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

Nie możesz wywnioskować niczego na podstawie braku komentarza, a komentarz może oczywiście być tak samo błędny jak otaczający kod lub więcej. Wyrok musi być wykonywany zarówno przez autora, jak i czytelnika.

Komentowanie każdej linii to wyraźnie więcej pracy o wątpliwej wartości dodatkowej, która wiąże się z kosztem alternatywnym. Jeśli masz regułę, która mówi, że każdy wiersz musi zostać skomentowany, dostaniesz to, ale kosztem ważnych części, które zostaną dobrze skomentowane .

Ale jest jeszcze gorzej: cel komentarza zostaje pokonany, jeśli każdy wiersz jest komentowany. Komentarze stają się szumem, który sprawia, że ​​kod jest trudny do odczytania: raczej zaciemnia niż wyjaśnia. Co więcej, bezkrytyczne komentowanie utrudnia zauważenie naprawdę ważnych komentarzy.

Ani komentarze, ani dokumentacja nie zapewniają żadnego rodzaju miary ani gwarancji jakości opisywanego kodu; nie zastępują one prawdziwej kontroli jakości. Ich celem jest wybieganie w przyszłość, tj. W nadziei, że pomogą tym, którzy z nią wejdą, uniknąć błędów.

Podsumowując , standardy kodowania mogą i powinny wymagać dokumentacji (automatyczne kontrole pomagają wykryć nieudokumentowane funkcje / metody, ale ludzie nadal muszą sprawdzać, czy dokumentacja jest dobra). Komentarze są zaproszeniem do oceny, a przewodnik po stylu powinien to potwierdzić. Ci, którzy nigdy nie komentują, i ci, którzy komentują bez namysłu, powinni spodziewać się wyzwania.

Nie możesz skodyfikować standardu komentowania, ponieważ nie wiesz z góry, jaki będzie ważny komentarz.

Ale nadal chcesz się upewnić, że kod jest poprawnie skomentowany, ponieważ jest to kod krytyczny dla życia. Rozwiązaniem jest posiadanie standardu przeglądu kodu - wymaga, aby przegląd kodu komentował zrozumiałość.

Nie gwarantuje to, że nie zmieni się w bezsensowną listę kontrolną, ale przynajmniej powstrzyma ją przed utrudnianiem odczytu kodu. I ma możliwość ulepszenia.

Wymaga to kultury, w której przegląd kodu sam w sobie nie jest bezsensownym gestem, w którym odesłanie kodu tak trudnego do odczytania jest dobrą rzeczą, a nie zniewagą ani irytacją. Równie ważne jest to, że stwierdzenie, że było niejasne, nie jest postrzegane jako porażka czytelnika.

Nieczytelny kod jest do pewnego stopnia nieunikniony. Ponieważ pisarz jest zanurzony w kontekście i zobaczy coś oczywistego, gdy będzie to oczywiste tylko wtedy, gdy znasz x, y lub z.

Tak więc nie będziesz mieć reguły, która mówi, że dajesz dobre opinie, ale możesz na miejscu sprawdzić recenzje. Nawet menedżer niebędący programistą mógłby to zrobić - ponieważ prawdziwym pytaniem nie było to, czy kod został napisany, aby był czytelny, ale czy kod był rzeczywiście czytelny, o czym może decydować tylko ktoś, kto go przeczyta.

Skomentować każdą linię kodu? Nie .

Celem innych zasad, o których mówisz, jest właśnie tego uniknięcie.

Komentarze do czytelnego kodu są w najlepszym wypadku zbędne, aw najgorszym przypadku odstraszą czytelnika od szukania nieistniejącego celu komentarza.

Jeśli skomentujesz cały kod, który jest zrozumiały dla ciebie, podwoisz ilość czytania bez podawania jakichkolwiek dodatkowych informacji. Nie jestem pewien, czy taka redundancja się opłaci. Można sobie wyobrazić recenzenta mówiącego, że 42 mówi „ display_error”, podczas gdy komentarz mówi „wyświetla ostrzeżenie”. Ale wyobraź sobie zmianę w kodzie. Masz teraz dwa miejsca do poprawienia. Staje się jasne, że ten styl ma negatywy kopiuj-wklej.

Powiedziałbym, że optymalnie kod nie powinien wymagać żadnych komentarzy poza dokumentacją.

Istnieją style, które są całkowicie przeciwne, jeśli masz wątpliwości co do linii, to albo:

1. Kod jest zbyt skomplikowany i powinien zostać przekształcony w funkcję o nazwie o znaczeniu semantycznym dla części kodu. Czy to kompleks, ifczy część algorytmu. (Lub sprytny jednowarstwowy LINQ)

2. Jeśli nie można tego uprościć, nie znasz wystarczającej liczby idiomów języka.

(Osobiście nie jestem fanatykiem ścisłej zasady „brak komentarzy”, ale uważam, że jest to dobry początkowy sposób myślenia.)

Biorąc to wszystko pod uwagę, czy w ogóle można napisać dobre standardy kodowania, które wychwytują ten pomysł?

Co do procesu. Nasz standard bardzo mocno docenił recenzenta. Zakładając, że nie są złośliwe, działa to dobrze.

Kiedy pyta „Co to jest zmienna o?”, Zmieniasz jej nazwę. Jeśli zapyta, co robi ten blok, refaktoryzuj lub skomentuj. Jeśli toczyła się debata, czy coś jest jasne, czy nie, jeśli recenzent tego nie dostał, to z definicji tak nie jest. W bardzo rzadkich przypadkach było coś takiego jak 2. opinia kilku znajomych.

Średnio programista powinien otrzymać kod zrozumiały dla przeciętnego programisty w zespole. IMO powstrzymuje zbędne informacje i zapewnia, że ​​kod jest zrozumiały dla przynajmniej jednego innego członka zespołu, co uważamy za dobre optymalne.

Ponadto, nie było absoluty . Chociaż byliśmy małą grupą. Łatwo jest znaleźć konsensus w grupie 5 osób.

Pytanie:

Biorąc to wszystko pod uwagę, czy w ogóle można napisać dobre standardy kodowania, które wychwytują ten pomysł? Te, które będą istotne w recenzowaniu, ale nie zmienią się w bezmyślną listę kontrolną, która generuje notatki nie bardziej pomocne niż: „Zapomniałeś skomentować w linii 42”.

Komentarze nie powinny mieć na celu edukowania czytelnika na temat języka. Należy założyć, że czytelnik zna język lepiej niż pisarz, ale w znacznie mniejszym kontekście niż pisarz.

Czytelnik tego kodu z twojego przykładu powinien wiedzieć, że exit()zamknie aplikację - w ten sposób komentarz stanie się zbędny:

/* Exit the application */
exit();

Nadmiarowe komentarze stanowią naruszenie zasady DRY, a zmiany w kodzie niekoniecznie przenoszą się na komentarze, pozostawiając komentarze, które nie odzwierciedlają tego, co faktycznie robi kod.

Jednak komentarze wyjaśniające, dlaczego coś robisz, mogą być cenne - zwłaszcza jeśli nie możesz łatwo przekazać znaczenia w samym kodzie.

Python PEP 8 (przewodnik po stylu dla Pythona w standardowej bibliotece CPython) zapewnia następujące wytyczne dla wbudowanych komentarzy:

Oszczędnie używaj wbudowanych komentarzy.

Komentarz śródliniowy jest komentarzem w tym samym wierszu co oświadczenie. Komentarze śródliniowe powinny być oddzielone co najmniej dwiema spacjami od instrukcji. Powinny zaczynać się od # i pojedynczej spacji.

Komentarze wewnętrzne są niepotrzebne i w rzeczywistości rozpraszają uwagę, jeśli zawierają oczywiste. Nie rób tego:

x = x + 1                 # Increment x

Ale czasami jest to przydatne:

x = x + 1                 # Compensate for border

Biorąc pod uwagę taki przykład, osobiście wolę pójść o krok dalej i staram się również wyeliminować ten komentarz. Na przykład mogę dotrzeć do:

border_compensation = 1
compensated_x = x + border_compensation

Uczynienie kodu własnym dokumentem nie jest nowym pomysłem .

Powrót do aktualnego pytania:

Biorąc to wszystko pod uwagę, czy w ogóle można napisać dobre standardy kodowania, które wychwytują ten pomysł?

Uważam, że wytyczne i przykład PEP 8 pokazują dobry standard kodowania, który uwzględnia tę ideę. Więc tak, wierzę, że jest to możliwe.

Myślę, że kiedy widzisz tego rodzaju komentarze, a ja czasami tak to piszę, to dlatego, że autor pisze specyfikację w komentarzach, a następnie przegląda i implementuje każdy komentarz.

Jeśli mamy za zadanie napisać standard kodowania, który tworzy kod, który jest zrozumiały pod względem wymaganej funkcjonalności, a nie faktycznej funkcjonalności (aby można było wykryć błędy), to czy naprawdę rozmawiamy o tym, jak specyfikacje są definiowane, dokumentowane i powiązane z produkt końcowy?

edytować ----

Aby wyjaśnic. Nie wchodzę w komentarze vs testy TDD vs testy jednostkowe, które najlepiej. Lub sugerowanie komentarza w wierszu jest dobrym / złym

Podaję tylko powód, dla którego możesz zobaczyć styl komentowania opisany w przykładzie.

Na podstawie tego pytania, czy norma kodowania dotycząca komentowania byłaby w rzeczywistości lepiej napisana jako pewnego rodzaju wymóg dokumentu specyfikacji.

tzn. komentarze służą wyjaśnieniu celu kodu, który jest również specyfikacją

Biorąc to wszystko pod uwagę, czy w ogóle można napisać dobre standardy kodowania, które wychwytują ten pomysł? Te, które będą istotne w recenzowaniu, ale nie zmienią się w bezmyślną listę kontrolną, która generuje notatki nie bardziej pomocne niż: „Zapomniałeś skomentować w linii 42”.

To oczywiście wykracza poza dokumentację - dotyczy to struktury kodu, wybieranych algorytmów itp. Może nawet dotyczyć analizy i projektowania wymagań.

Moja zasada nr 1 brzmi: „Nie dokumentuj rzeczy oczywistych”. Zasada nr 2 to „Napisz oczywisty kod”.

W przypadku kodu krytycznego dla bezpieczeństwa (nad którym nigdy nie musiałem pracować, dzięki Bogu) jest to konieczny, ale nigdzie blisko wystarczający pierwszy krok. Może nawet trzeba sprowadzić się do określenia, jakich funkcji językowych należy unikać (widziałem więcej niż jedno standardowe polecenie „Nie będziesz używać scanf( "%s", input ); z jakiegokolwiek powodu ”).

Najlepsza praktyka w zakresie samo-dokumentowania kodu nie stanowi głównego nurtu konsensusu - podczas gdy powszechnie akceptowalny jest fakt, że łatwy do zrozumienia kod jest lepszy niż kod szyfrujący, nie wszyscy są zgodni co do tego, czy skomplikowany kod musi być zawsze refaktoryzowany, czy też czy można komentować to.

Ale ta debata dotyczy fragmentów kodu, które są trudne do zrozumienia - a ty mówisz o komentowaniu każdego wiersza kodu. Linie kodu, które są trudne do zrozumienia, powinny być bardzo rzadkie - jeśli większość twoich linii jest tak skomplikowana, niż nadmiernie używasz inteligentnych duplikatów i powinieneś przestać! Oczywiście rola linii może być czasem trudna do zrozumienia, ale taka jest rola w kontekście większego fragmentu kodu - to, co robi sama linia, jest prawie zawsze proste.

Więc nie powinieneś komentować wierszy - powinieneś komentować fragmenty kodu. Konkretne komentarze mogą być umieszczone w pobliżu wierszy, do których się odnoszą, ale komentarze te wciąż odnoszą się do większego kodu. Nie opisują, co / dlaczego robi wiersz - opisują, co robi w tym kodzie i / lub dlaczego jest on potrzebny w tym kodzie.

Tak więc to nie wiersze powinny być komentowane, ale większe fragmenty kodu. Czy każdy fragment kodu powinien być komentowany? Nie. Harold Abelson powiedział, że „ Programy muszą być napisane, aby ludzie mogli je czytać, a tylko przypadkowo, aby maszyny mogły je uruchomić ”. Ale komentarze są tylko dla ludzi do czytania - maszyna ich nie wykonuje. Jeśli twoje standardy kodowania wymuszają pisanie zbędnych komentarzy do każdej linii / fragmentu kodu, nie tylko obciążasz programistę, który musi je napisać - obciążasz również programistów, którzy będą musieli je przeczytać !

Jest to problem, ponieważ gdy większość komentarzy, które czytasz, są zbędne, przestajesz zwracać na nie uwagę (ponieważ wiesz, że będą to zbędne śmieci), a następnie przegapisz ważne komentarze. Mówię więc - napisz tylko ważny komentarz, aby gdy ktoś zobaczy komentarz w kodzie, będzie wiedział, że warto go przeczytać, aby zrozumieć kod.

IMHO powinno to zrobić jedno i drugie. Komentowanie każdej linii jest głupie, ponieważ kończysz na liniach takich jak

  i++;    /* Increment i */

bez absolutnie żadnego pojęcia, dlaczego chcesz zwiększyć. Rozwiń to trochę, a masz typowy styl komentarzy Doxygen, które generują dużą liczbę słów bez podania, do czego służy kod i jak działa. (Przynajmniej o ile kiedykolwiek widziałem: przyznaję, że możliwe byłoby napisanie przydatnej dokumentacji przy użyciu takiego systemu, ale nie wstrzymuję oddechu.)

OTOH, jeśli napiszesz dobry blok komentarza na początku funkcji (lub jakiekolwiek logiczne grupowanie), opisując zarówno, co należy osiągnąć, jak i, jeśli jest to mniej niż oczywiste, masz coś, co jest przydatne. Jeśli jesteś mną, możesz nawet dołączyć kod LaTeX dla odpowiednich równań lub odniesienia do artykułów, np. „To implementuje schemat WENO do rozwiązywania równań Hamiltona-Jacobiego, jak omówiono w ...”

Czas przywrócić wykresy przepływu! (nie bardzo, ale poczekaj chwilę)

Innego dnia znalazłem mój stary szablon schematu blokowego. Użyłem go tylko do odrabiania lekcji i żartów (musisz pokochać dobry, głupiutki schemat blokowy). Ale nawet do tego czasu większość komercyjnych programistów, którzy nadal używali schematów blokowych, generowało je automatycznie z kodu (co całkowicie podważa pierwotny cel schematu blokowego, który miał być pomocnikiem w pisaniu lepszego kodu i był bardzo przydatny w kodzie maszynowym. Jednak w przypadku języków wyższego poziomu schemat blokowy zmienił się z kuli w szlachetnego. Dlaczego? Abstrakcja schematu blokowego była taka sama jak kod. Przedstawione komentarze są kulawe, ponieważ są na tym samym poziomie abstrakcji co kod. Dobre komentarze mają inny poziom abstrakcji niż kod. Najłatwiej to zrobić, używając komentarzy, podczas gdy kod obsługuje co.

Odpowiem na pytanie, jak podano:

Biorąc to wszystko pod uwagę, czy w ogóle można napisać dobre standardy kodowania, które wychwytują ten pomysł?

Tak. WYSIWYG. Dobry standard kodowania to dosłownie „ dla czytelnika jasne jest, co robi poniższy kod i dlaczego ”.

Innymi słowy, mój komentarz do przeglądu kodu na temat czytelności kodu dosłownie, 1-1, wynika z mojego stanu psychicznego

Ja, jako czytelnik (jeszcze lepiej, jako minimalny standard, mentalny model mniej doświadczonego, ale rozsądnego czytelnika), nie rozumiem celu następującego kodu lub metody działania

Zasadniczo ludzie łatwo wchodzą na pokład „to wymaga większej czytelności”, gdy słyszą „ja, jako starszy programista, który, jak mam nadzieję, szanujesz, nie jest głupi, nie przeczytałem na początku tego kodu ani tego, dlaczego on jest, ani co to robi, więc trzeba to wyjaśnić ".

To zmienia dyskurs z „nie przestrzegałeś bezsensownego standardu” na „twój kod ma specyficzny brak czytelności prowadzący do praktycznego problemu ”.

Drugim standardem, który należy wyjaśnić, jest „test awaryjny o 2 nad ranem”.

Czy twoja kopia zapasowa, która nie ma doświadczenia z tym kodem, może odkryć, na czym polega problem z kodem podczas debugowania go podczas awaryjnego połączenia z mostem produkcyjnym o 2 nad ranem, gdy jesteś na wakacjach w chilijskich Andach bez telefonu komórkowego?

Może to zabrzmieć subiektywnie, ale w rzeczywistości jest łatwe do zmierzenia: zadzwoń do przypadkowego młodszego członka zespołu, który prawdopodobnie będzie tym, który debuguje w nocy w nagłych przypadkach, i poproś go o wyjaśnienie, w jaki sposób działa dany nieskomentowany kod i dlaczego tam.

Ta odpowiedź obejmowała większość zagadnień, jednak jest jedna ważna rzecz.

Chciałbym uchwycić pomysł w następujący sposób: rozważ komentarz dla każdej linii, sekwencji, instrukcji, sekcji, struktury, funkcji, metody, klasy, pakietu, komponentu, ... kodu.

Istnieją narzędzia do generowania dokumentacji z kodu, takie jak na przykład doxygen. Jeśli używasz takich narzędzi, to komentowanie plików, funkcji, klas itp. Ma sens. Nawet jeśli nazwa funkcji jest oczywista, wciąż robię to dla zachowania spójności, ponieważ osoby czytające dokumentację będą wdzięczne.

Wiele istniejących odpowiedzi jest bardzo szczegółowych, ale czułem, że ważne jest, aby odpowiedzieć:

... [komentarze], które będą istotne w recenzowaniu, ale nie zamieniają się w bezmyślną listę kontrolną ...

Dla mnie na jedyne komentarze, które mogą być standardem, można odpowiedzieć, pytając, jakie komentarze są zauważane, gdy ich brakuje . Innymi słowy: komentarze używane przez IDE lub oprogramowanie dokumentacyjne.

Biorąc to pod uwagę, jest to subiektywne w stosunku do narzędzi używanych przez programistów i nie wszystkie komentarze używane przez takie oprogramowanie są tak przydatne, jak siebie nawzajem .