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

142

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

candied_orange
źródło
21
Komentarze nie są przeznaczone do rozszerzonej dyskusji; ta rozmowa została przeniesiona do czatu .
wałek klonowy
32
„Komentarze nie są przeznaczone do rozszerzonej dyskusji”, nawet bardziej prawdziwe w przypadku komentarzy do kodu. :) Te /* Display an error message */komentarze są okropne i faktycznie wpływają na czytelność.
Andrea Lazzarotto,
Potrzebujemy naszych IDE, aby mieć opcje ukrywania komentarzy. Może opcja ukrywania osobno zarówno komentarza blokowego, jak i wbudowanego. W ten sposób masz najlepszą z obu opcji. Umieść wiele komentarzy, ale możesz je ukryć, aby kod był czysty i uporządkowany.
Doug.McFarlane
1
@ Doug.McFarlane Myślałem, że powinien istnieć dla vima. Oczywiście robi to zarówno na poziomie pliku, jak i bloku - rtfm-sarl.ch/articles/hide-comments.html !
Michael Durrant
1
Również przełączanie - stackoverflow.com/a/11842371/631619
Michael Durrant

Odpowiedzi:

171

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.

Doktor Brown
źródło
45
Kto to ocenił? To odpowiedź na krytyczne rozwoju oprogramowania. To jest inny świat niż ten, w którym pracuje większość programistów. W tych światach standard kodowania, który wymaga, aby każdy wiersz kodu miał swój własny komentarz, nie jest właściwą odpowiedzią. Ani też nie przekazuje komentarzy. OTOH, poddawanie komentarzy przeglądowi kodu jest właściwym rodzajem standardu dla krytycznego oprogramowania. To sprawia, że ​​kod jest łatwiejszy do przeglądu i konserwacji, ale wiąże się to z pewnym kosztem. To koszt blednie w porównaniu z wielomilionowymi procesami sądowymi wynikającymi ze źle napisanego oprogramowania.
David Hammen,
4
mądra odpowiedź. gdybyśmy mogli znaleźć prawdziwe zasady kodowania, nie potrzebowalibyśmy programistów. możemy po prostu mieć kod maszynowy. to może się zdarzyć! :(
4
@DavidHammen: dzięki za komentarz. Właściwie myślę, że dotyczy to nie tylko „krytycznego rozwoju oprogramowania”. Każde oprogramowanie, które jest utrzymywane i rozwijane przez lata, często przez różne osoby, skorzysta z tego, że będzie zrozumiałe dla następnego programisty konserwacji.
Doc Brown
5
To dobra rada dla każdego kodowania, nie tylko dla kodu obsługiwanego przez różne osoby. Nawet jeśli jesteś jedynym, który używa skryptu / programu, przyszłość, którą musisz zmodyfikować kod za rok, doceni jasność (i czas zaoszczędzony dzięki temu, że nie będziesz musiał rozszyfrować nieprzejrzystego kodu).
Anthony Geoghegan
5
Czy możesz edytować „najbardziej uprzywilejowaną odpowiedź” na coś bardziej obiektywnego? Nie każdy czytelnik pozna historię głosowania na te odpowiedzi.
candied_orange
151

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

Michael Durrant
źródło
8
Nie wierzę, że odpowiedziałeś na pytanie. Pytanie nie dotyczy komentarzy w każdej linii. Pyta, jak powiedzieć programistom, aby skomentowali kod, nie zmuszając ich do komentowania każdej linii.
hichris123
7
Tak, nie odpowiadam na pytanie dotyczące konkretnych standardów, ale próbuję pomóc ludziom nie pójść tą drogą. Może to nie być odpowiedź na konkretne pytanie, ale zawiera cenne porady, które trudno jest przedstawić w komentarzu.
Michael Durrant
1
Jaki jest inny trudny problem?
David Grinberg,
1
Każdemu z powodów, dla których należy unikać komentarzy, można przeciwdziałać, ale StackExchange nie zezwala na wystarczająco długie komentarze (heh), żebym mógł je tutaj wszystkie rozwiązać. Po prostu: przeszacowanie jest jak oszustwo wyborców: zdarza się, ale bardzo rzadko; kiedy ostatni raz to widziałeś? Pisanie dobrych komentarzy nie powinno być zwykłą refleksją; jeśli wykonane poprawnie, pomaga w procesie rozwoju. Tak, zajmuje zasoby, ale spłatą jest lepszy kod. Nigdy nie będziesz w stanie uzyskać takiego samego huku za swoje pieniądze, poświęcając komentarze dla lepszego standardu nazewnictwa zmiennych. Tak, komentowanie każdej linii jest szalone.
kmoser
23

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.

JacquesB
źródło
63
Jedną z wielu rzeczy, których nauczyłem się po ponad 40 latach w tej grze, jest to, że zdrowy rozsądek wcale nie jest powszechny.
John R. Strohm,
10
Nie ma czegoś takiego jak zdrowy rozsądek.
whatsisname
1
in_programming no .. real world o tak, ale to tylko termin na wiedzę z prawdziwego świata
Michael Durrant
@ JohnR.Strohm: Moje doświadczenie było znacznie bardziej pozytywne niż twoje, ale widziałem również, jak można skutecznie zniechęcać do korzystania ze zdrowego rozsądku przez mechaniczne egzekwowanie reguł.
JacquesB
Zgadzam się z tą odpowiedzią w 99,9%. Standard kodowania ma być tym, na co deweloperzy zwracają uwagę podczas debaty w Code Review. Przegląd kodu ma na celu wzbogacenie produktu, a nie rozpoczęcie wojen. Tyle wojen, które widziałem wywołane przez Code Reviews bez standardu kodowania. Śmiem twierdzić, że jeśli nie możesz zautomatyzować sprawdzania pozycji w standardzie kodowania, powinno tam być. Przegląd kodu to czas na przekazanie „zdrowego rozsądku” innym mniej doświadczonym programistom. To nie czas na walkę o nazewnictwo zmiennych. linux / kernel / gen_init_cpio.c linia 335.
Andrew T Finnell
19

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.

Jaka jest nazwa?
źródło
1
+1 za „Próbujesz zmechanizować dobry osąd”, -1 za „Twoja jedyna opcja to po prostu mieć nadzieję na najlepsze”, a to nie daje mi głosu. Opcją jest także kształcenie i szkolenie swojego zespołu. Normy mogą pozwolić na osąd.
Wildcard
1
@Wildcard Być może mógłbyś wyjaśnić, w jaki sposób Standard może pozwolić na osąd? Czy w tym momencie nie byłby to Przewodnik? Norma to „idea lub rzecz używana jako miara, norma lub model w ocenach porównawczych”. Jak można użyć czegoś z natury subiektywnego, tak subiektywnego, że zależy to od tego, kto to czyta, jako miary jakości?
Andrew T Finnell,
1
@Wildcard: Problem polega na tym, że kiedy wchodzisz w regulowane gałęzie przemysłu, proces panuje nad wszystkim, posiadanie procesu jest ważniejsze niż to, czy jest to opłacalne, czy nie. Wszystko musi sprowadzać się do pól wyboru w jakiejś formie, każde pole wyboru musi być konkretne i weryfikowalne, a im więcej masz pola wyboru w polu wyboru, tym większe ryzyko, że będziesz mieć problem z audytem.
whatsisname
To dziwny świat i pamiętaj, że reguły są pisane przez biurokratów z niewielką wiedzą na temat dziedziny oprogramowania. Często kończy się to na systemach, które istnieją po to, aby usprawiedliwić się i wymagać od siebie samych, a nie być środkiem do osiągnięcia celu zapewnienia wysokiej jakości produktów.
whatsisname
1
@whatsisname Bardzo się cieszę, że ktoś jeszcze to rozumie. Wasze odpowiedzi są napisane bardziej elegancko i precyzyjnie, niż mogłem do tej pory dążyć. Oświadczenie with systems that exist to justify and require themselves rather than being a means to an end to ensure quality productsjest DOKŁADNIE tym, co próbowałem zilustrować. Dziękuję za znalezienie moich słów dla mnie. Naprawdę to mam na myśli. Musimy oddzielić ideę indukowania jakości od idei wykonania procesu, ponieważ nie są one takie same. Dlatego mamy QA, Stackoverflow i bardzo wybaczających klientów.
Andrew T Finnell,
14

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.

Andrew T Finnell
źródło
3
Problem z komentarzami polega na tym, że NIE mają one wpływu na ostateczny sposób działania produktu. cóż, jeśli liczy się ludzka część czytania i pisania kodu, myślę, że ma to wpływ na to, jak ostatecznie to działa, ale nie na sposób, w jaki kod wykonuje się po napisaniu, tak. Powiedziałbym, że problem z kodem polega na tym, że staje się on przestarzały, a następnie gorszy niż brak kodu!
Michael Durrant,
1
Tutaj mieliśmy mierzącego czas, który chciał codziennych raportów z tego, co zrobiliśmy, aby mógł on nadmiernie zoptymalizować naszą pracę. W niektórych przypadkach byliśmy trochę źli z powodu faktu, że musieliśmy spędzać 15 minut każdego dnia, wypełniając jego formularz, więc zautomatyzowaliśmy to, wypełniając śmieci z naszych dzienników.
joojaa,
1
Istnieje dodatkowy problem z komentarzem „Nie dzielimy przez 0, aby zatrzymać awarie”. Gramatycznie nie jest jasne, czy klauzula „w celu” dotyczy akcji podziału, czy też jej negacji. Jeśli użyjesz „Unikamy dzielenia przez 0, aby ...” unikniesz tej dwuznaczności. :)
Wildcard
1
„nie dziel przez zero, aby zatrzymać awarie”, tak naprawdę mówi mi wiele o sposobie myślenia osoby, która to napisała. Nie kodujesz, aby uniknąć awarii! Kodujesz tak, aby kod był poprawny, a nie zawieszanie się to tylko niewielka część poprawności. Jeśli obliczenia ilości leku do wstrzyknięcia zostaną podzielone przez zero, nie
zwrócisz żadnej sztucznej
1
@AndrewTFinnell Mam na myśli to, że jeśli czasami otrzymasz błąd dzielenia przez zero, dodanie „if (divisor == 0) return <something>; // Unikaj dzielenia przez zero” nie poprawia twojego kodu. Zamiast tego musisz dowiedzieć się, dlaczego dzielnik wynosi zero i to naprawić. Niektóre algorytmy są tak zaprojektowane, że dzielnik zerowy jest nieunikniony, ale stanowią wyjątek (w takim przypadku możesz zwrócić wartość „wynik nie może być obliczony”).
immibis
12

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.

użytkownik52889
źródło
Udokumentowanie publicznego API jest dobrą rzeczą, ale naprawdę lubię wyjaśniać zaskakujące decyzje. To bardzo miłe, jeśli naruszenie zasady najmniejszego zdziwienia ma przynajmniej uzasadnienie. +1
candied_orange
1
+1 za obce komentarze jako hałas. Utrzymuj wysoki poziom sygnału hałasu.
sq33G
+1, zwłaszcza na potrzeby komentarza, zostaje pokonane, jeśli każdy wiersz jest komentowany. Szkoda, że ​​może to być (i często jest) wykorzystywane jako wymówka, aby w ogóle nie komentować, ale i tak jest to bardzo słuszne, z powodów, o których wspomniałeś, plus, ponieważ jeśli każdy wiersz zostanie skomentowany, większość ludzi automatycznie i zrozumiale zacznie ignorować wszystkie komentarze .
SantiBailors
10

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.

jmoreno
źródło
7
Re Nie możesz skodyfikować standardu komentowania - Jasne, że możesz. Komentarze podlegają przeglądowi kodu, a ten element przeglądu kodu, który mówi, że komentarze nie wyjaśniają kodu, musi zostać rozwiązany. Jest to wydatek, wydatek, którego większość środowisk programistycznych nie chce ponosić. Opłaca się w odniesieniu do krytycznego oprogramowania.
David Hammen,
„... gdy jest to oczywiste, jeśli znasz x, y lub z” Możesz określić ilość wiedzy {x, y, z}, która musi być znana z góry, aby zobaczyć coś tak oczywistego, a następnie (miły) z mechanicznie) możesz sprawdzić, czy dotyczy to bieżącego kodu. Gdzie nie, dodawaj komentarze, dopóki nie będą.
Trilarion
1
@DavidHammen: to nie jest standard dla komentarza, to standard dla recenzji. Właśnie to zaproponowałem jako rozwiązanie. Nie możesz powiedzieć, że musi mieć określony rozmiar, użyć określonej składni, a nawet pożytecznie wymagać komentarza w pierwszej kolejności (lub dostajesz komentarze „dodaj jeden do i”). Możesz powiedzieć, że recenzent musi skomentować kod i komentarze. Jak mówisz, możesz wymagać rozwiązania problemów związanych z przeglądem kodu. Ale ciężar MUSI spoczywać na recenzencie, by wykonał dobrą robotę. Tylko recenzent może ocenić, czy kod i komentarz są wystarczające.
jmoreno
@DavidHammen Ludzie wybrani do przeglądu wzywają wyrok? A kiedy odejdą? Jeśli nowi ludzie nie myślą w ten sam sposób lub nie mówią po angielsku? Jeśli „recenzenci” odejdą? Twoja sugestia stawia kilku programistów na Wieży Kości Słoniowej, co prowadzi do sprzeciwu, nieufności i zerwania komunikacji. Komentarze mają na celu zapewnić wgląd lub wyjaśnienie dla tych, którzy mogą z niego korzystać. Być może Joe tego potrzebuje, ale Mary nie. Co się stanie, gdy Mary będzie recenzentem? Czy Joe? Lub Mark?
Andrew T Finnell,
@jmoreno - Brak umieszczania reguł / wytycznych dotyczących komentarzy w standardach kodowania oznacza, że ​​programiści muszą patrzeć na wiele źródeł - i nie wiedzą, gdzie szukać, dopóki recenzja nie wróci, mówiąc, że komentarze są poniżej normy. Błędem jest myśleć, że wszystko w standardzie kodowania musi być zautomatyzowane. Na przykład reguły dotyczące znaczących nazw nie są automatyczne. Przynajmniej jeszcze nie. Na przykład x, yi z, lub i, ji kmoże być całkiem sensowne nazwy jeśli ktoś realizuje algorytm naukowe na podstawie dokumentu księgowego, który używany dokładnie te nazwiska w swoich formułach.
David Hammen
9

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.

luk32
źródło
2
Korzystanie z recenzji kodu w celu dyktowania nazw zmiennych, klas i metod to najlepszy sposób, aby ludzie nienawidzili firmy, firmy lub metodologii. Przeglądy kodu nie powinny być wykorzystywane do egzekwowania rzeczy, które tak naprawdę nie mają znaczenia. Standard kodowania musi być możliwy do sprawdzenia w zautomatyzowanym procesie. Zmienna długość nazwy, złożoność kołowa, prawo demetera to wszystko, co można sprawdzić. Gdyby ktoś kazał mi zmienić nazwę zmiennej z „i” na coś takiego jak indexForThePreviousCollection, znalazłbym inne miejsce do pracy. Zmienne> 3 znaki są sprawdzane przed automatycznym zameldowaniem.
Andrew T Finnell,
3
@AndrewTFinnell Potrafię napisać niemożliwy do naśladowania kod w dowolnym paradygmacie programistycznym, który chcesz nazwać.
candied_orange
2
@AndrewTFinnell Cóż, grzecznie się nie zgodzę. „ Używam recenzji kodu do dyktowania ”, nie wiem, skąd go wziąłeś. Nie chciałbym, aby pracować nad kodem ze zmiennymi i, j, kwszędzie po jego autor zostanie zamknięty. Nie rozumiem twojego zdania na temat „ludzkiego” genomu. Wątpię, by istniał język, w którym są pojedyncze stwierdzenia, lub dwa są zbyt trudne do zrozumienia. Jak powiedziałem, widziałem złożone ifs i LINQjedno-liniowe. Można je komentować lub refaktoryzować pod semantycznie znaczącą nazwą, tak myślę, to jest twój „dobry komentarz”.
luk32
3
@ luk32 Szanuję prawo do odmowy. Moim zdaniem zmienne iteracyjne są dość kontekstowo oczywiste. Chociaż rozumiem sentencję twojego oświadczenia, uważam, że istnieje zbyt wiele praktyk, które podnoszą to uczucie do granic możliwości. Czy naprawdę potrzebujemy kodu, który brzmi: for (int indexForCurrentDatabaseRow = 0; indexForCurrentDatabaseRow < currentUserRecordSetResults.length; indexForCurrentDatabaseRow = indexForCurrentDatabaseRow + 1)kontra for (int i = 0; i < results.length; i++)? Być może jest to kwestia preferencji i / lub czasu poświęconego na przeglądanie kodu. Nadmiernie pełne imiona pachną dla mnie.
Andrew T Finnell,
2
Nie sądzę, że nazwy powinny być ustalane w recenzjach kodu. Przegląd kodu powinien zwykle rozpocząć się, gdy autor uzna, że ​​jest wystarczająco dobry, co oznacza również, że jest odpowiednio skomentowany, łatwy do zrozumienia, a zmienne mają przyzwoite nazwy. Chodzi o to, że jeśli recenzenci uważają, że kod jest zbyt skomplikowany lub mają problemy ze znaczeniem zmiennej, kod jest trudny do zrozumienia. To nie jest dyskusyjne - najwyraźniej przynajmniej jeden programista - recenzent - nie zrozumiał tego. To, czy należy to refaktoryzować (i jak) lub odpowiednio skomentować, to inna sprawa.
Idan Arye,
9

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.

Aaron Hall
źródło
1
„Należy założyć, że czytelnik zna język lepiej niż pisarz”. Trudno mi uwierzyć, że to właściwe podejście. Widzę, że zakładają, że wiedzą tyle , ale każda drużyna jest inna, a każda osoba w drużynie jest inna, więc ogólne stwierdzenie w tej konkretnej kwestii nie wydaje się mądre.
Bryan Oakley,
4
Bez tych wskazówek młodsi programiści będą publikować komentarze wyjaśniające trywialny kod nikomu innemu, a programiści średniego szczebla używają niezręcznych rozwiązań, aby po prostu uczynić kod bardziej dostępnym dla młodszych programistów. Te wskazówki eliminują nadmiarowość i zapewniają, że nawet biegły programista nadal ulepsza swój kod. Kiedy ponownie odwiedzam kod, mogłem zapomnieć o kontekście, ale ogólnie wiem, co robi ten język, nawet lepiej niż kiedy go pisałem.
Aaron Hall
4

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ą

Ewan
źródło
6
Przez 20 lat nigdy nie widziałem, aby ktoś komentował w ten sposób swój kod, a następnie uzupełniał luki w rzeczywistym kodzie. Istnieje już obiektywny sposób na osiągnięcie tego, co mówisz lub co myślę, że mówisz. Nazywa się to Test Driven Development. Testy jednostkowe określają specyfikację i to, czy kod przestrzega tej specyfikacji. Wszystko bez komentarzy.
Andrew T Finnell,
9
Chociaż nie sądzę, aby kod w pytaniu był tego dobrym przykładem, praktyka pisania najpierw procedury w komentarzach, a następnie cofania się i wypełniania kodu jest wyraźnie nazywana w „Code Complete” jako jedna możliwe praktyki pomagające w tworzeniu czytelnego kodu, @AndrewTFinnell. Na pewno nie jest to niespotykane, nawet jeśli jest poza twoim doświadczeniem.
Josh Caswell
6
wierzę również przed datą TDD
Ewan
2
Czy mówisz o procesie programowania pseudokodu? Miało to na celu ograniczenie komentarzy. Nigdy nie pamiętam, żeby w kodzie pozostawić książkę z komentarzami. Komentowanie w celu opracowania procedury koncepcyjnej powinno być na wysokim poziomie, a nie na niskim poziomie. Gdyby ktoś skomentował każdą linię, którą zamierzał napisać, mogliby właśnie napisać linie. Chodzi o to, aby prototypować zasady kodu, a nie każdą linię. Książka nie sugeruje komentowania każdej linii. To jest sedno tego pytania. Mogę się mylić, ale wierzę, że tak jest w drugiej edycji.
Andrew T Finnell,
2
@JoshCaswell & Ewan, tak, to była technika wiele lat temu i rzeczywiście była wcześniejsza niż TDD. Ale miałeś później usunąć komentarze! A TDD całkowicie wyparło go jako rozsądny sposób tworzenia kodu, który spełnia specyfikację.
David Arno,
4

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

John Bode
źródło
Oczywiste są w oku patrzącego. I zmiany w zależności od terminu.
Tony Ennis,
3

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.

Idan Arye
źródło
1
Brak ważnych komentarzy: +1. Zdanie, które zaczyna się od: „Nie opisują”, może przydać się do restrukturyzacji, aby ułatwić przestrzeganie.
candied_orange
3

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

jamesqf
źródło
2
+1 za komentarz doxygen: To jest dokładnie mój sprzeciw wobec włączenia doxygen „dokumentacji” w moim kodzie; W 95% przypadków po prostu powtarza to, co już jest oczywiste z podpisu funkcji. Ja też nie widziałem jeszcze żadnej dokumentacji doksygen, która byłaby cokolwiek warta. Pisanie tych komentarzy trzykrotnie marnuje czas: Raz napisał komentarze, raz przeczytał je ponownie, a raz debugował problemy powstałe w wyniku przestarzałej treści komentarzy.
cmaster
1
Nie zaprzeczasz sobie? Myślę, że oboje zgodzilibyśmy się, że kluczowa jest funkcja, która ma komentarz opisujący to, co robi z perspektywy czarnej skrzynki - „te wejścia wchodzą, funkcja to robi, a te wyjścia wychodzą”. Jest to umowa między osobą, która napisała funkcję, a osobami, które z niej korzystają. Celem Doxygen jest po prostu ujednolicenie formatu tych komentarzy w sposób, który można przeanalizować i umożliwić przeszukiwanie / indeksowanie. Dlaczego więc miałbyś chcieć „dobrego bloku komentarzy”, a nie mieć standardowego formatu czytelnego dla ludzi i maszyn?
Graham
Korzystanie ze standardu komentarzy, takiego jak JSDoc, JavaDoc i Doxygen, ma na celu dostarczenie przeszukiwalnej i czytelnej dla ludzi dokumentacji, jak powiedział @Graham. Linia kodu wymieniona w tej odpowiedzi nie ma nic wspólnego z Doxygen. Nie mogę sobie nawet wyobrazić istnienia zestawu reguł, który analizowałby ten komentarz i tworzył wpis w wynikowej dokumentacji. Gdy spojrzysz na Dokumenty dla JMI, Standardowe biblioteki Java itp., Wszystkie są tworzone przy użyciu narzędzia bardzo podobnego do Doxygen. Taki jest cel tego. Nie to, co tu powiedziano
Andrew T. Finnell,
Nie zmyślam tego - aby spełnić wymagania kanadyjskie, w firmie, w której pracowałem, programiści napisali procesor wstępny, który dodawał komentarze DOKŁADNIE tak, jak przykład OP. Myślę, że naszym było „C ADD 1 TO I” lub coś takiego. Był to FORTRAN, więc podobnie polecono pętle „C LOOP FROM 1 to 10”. Kod został ZAŁADOWANY bezużytecznymi komentarzami. Usunąłem wszystkie te badziewie, gdy utrzymałem kod. Nikt mi nic nie powiedział.
Tony Ennis,
2

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.

Hildred
źródło
Z przykrością informuję, że schematy blokowe nigdy nie zniknęły.
Ant P
Dobre komentarze są na innym poziomie abstrakcji niż kod . Usłysz słyszeć!
candied_orange
1
Chociaż może to być przyzwoita rada, wydaje się, że nie odnosi się do postawionego pytania, z wyjątkiem jednego zdania.
Bryan Oakley,
0

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.

DVK
źródło
0

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.

BЈовић
źródło
1
Ale „dokumentacja” generowana przez takie narzędzia jest, przynajmniej z mojego doświadczenia, ogólnie warta mniej niż żadna dokumentacja, ponieważ nie dostarcza użytkownikowi użytecznych informacji (i powoduje, że marnują czas na wydobywanie nie- istniejące informacje), ale oszuka programistów, którzy myślą, że odpowiednio udokumentowali swój kod.
jamesqf
@jamesqf Tak, gdy połowa funkcji nie jest udokumentowana, a druga połowa źle. Jednak doxygen może generować całkiem dobrą dokumentację, zakładając, że programiści odpowiednio skomentowali swoje funkcje, klasy itp.
B
-1

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 .

Erdrik Ironrose
źródło