Miałem wyszukiwanie, ale nie znalazłem tego, czego szukałem, proszę o link, jeśli to pytanie zostało już zadane.

Wcześniej w tym miesiącu opublikowano ten post:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

Podsumowując, jesteś złym programistą, jeśli nie piszesz komentarzy. Osobiście uważam, że kod powinien być opisowy i przeważnie nie powinien wymagać komentarza, chyba że kod nie może być samoopisujący.

W podanym przykładzie

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

Autor powiedział, że ten kod powinien otrzymać komentarz, moja osobista opinia jest taka, że ​​kod powinien być wywołaniem funkcji o charakterze opisowym:

$extension = GetFileExtension($image_filename);

Jednak w komentarzach ktoś faktycznie przedstawił właśnie taką sugestię:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

Autor odpowiedział, mówiąc, że komentator był „jedną z tych osób”, tj. Złym programistą.

Jakie są inne opinie na temat kodu samoopisującego w porównaniu do kodu komentującego?

Wolę pisać kod samodokumentujący. Przewodnikiem tego jest Clean Code .

To oczywiście nie oznacza, że ​​nigdy nie należy używać komentarzy - mają swoją rolę, ale IMHO powinieneś ich używać ostrożnie. Ta moja wcześniejsza odpowiedź na temat SO wyjaśnia bardziej szczegółowo moje przemyślenia na ten temat.

Oczywiście, jak zauważył @Niphra, zawsze warto dwukrotnie sprawdzić, czy to, co uważam za czyste, jest naprawdę zrozumiałe dla innych. Jest to jednak również kwestia praktyki. Po powrocie do uni napisałem tajemnicze fragmenty kodu po prostu z powodu używania dziwnych i zabawnych nazw dla wszystkich jednostek kodu, zgodnie z moim kaprysem. Dopóki mój nauczyciel nie odrzucił jednego z moich zadań, uprzejmie zauważył, że nie mógł dowiedzieć się, który moduł był główny :-) To była dobra lekcja, więc od tego czasu starałem się skupić na pisaniu coraz bardziej czytelnego kodu. Obecnie prawie nie otrzymuję skarg od członków drużyny.

Nie powinieneś dokumentować tego, co robi kod, ale powinieneś udokumentować, dlaczego to robi.

Żadna sztuczka nazewnictwa nie ujawni, dlaczego i gdzie, więc musisz dodać komentarze, aby wyjaśnić cel różnych fragmentów kodu.

Wszystkie pozostałe komentarze można bezpiecznie się pozbyć.

Tak naprawdę nie wierzę w kod opisujący. Jest więcej czytelnego kodu i mniej czytelnego kodu , w zależności od języka, twojej wiedzy o nim (jako oryginalnego autora), wiedzy faceta czytającego go i funkcji kodu. Ale nie, wciąż ... należy to opisać krótkim komentarzem.

To, co teraz jest dla mnie jasne, że jestem w tym obszarze myślenia , prawdopodobnie nie będzie dla mnie jasne za rok, kiedy myślę o czymś zupełnie innym i potrzebuję ponownie użyć tej części kodu.

Więc skomentuj swój kod. Oczywiście nie każda linia (dobre niebiosa, nie), ale umieść kilka linii komentarza nad funkcją / podprogramem / modułem lub szczególnie trudną częścią i krótko opisz, co robi. Podziękujesz sobie za rok lub dwa.

Na szczęście oba obozy biorące udział w tej dyskusji są tutaj reprezentowane i wspomniano argumenty za i przeciw.

Uważam, że oba obozy mają zbieżne argumenty i faktycznie zgadzają się z większością z nich, po prostu sposób ich osiągnięcia jest nieco inny.

Nakładające się argumenty

• Kod powinien być czytelny.
• Komentarze nie powinny zawierać dokładnie tego samego, co kod, ale w razie potrzeby dają dodatkowe informacje.
• Wszystkie nazwy zmiennych / funkcji powinny być dobrze przemyślane, aby dobrze reprezentowały to, czym są / robią.
• Duplikatowi kodu należy zapobiegać.

Główna różnica polega na tym, ile wagi przypisuje się niektórym z tych argumentów.

Kod samoopisujący

• Komentarze mogą stać się przestarzałe, więc zminimalizuj ich użycie, ponieważ złe komentarze są gorsze niż brak komentarzy.
• Komentarze są duplikatem kodu. Wszystko, co można napisać kodem, powinno być napisane kodem.

Więcej komentarzy

• Komentarze są bardziej czytelne niż kod. Zwykły angielski jest lepszy w opisywaniu czegoś.

• Zwykły kod często powoduje niejednoznaczność, którą i tak należy skomentować. Próba opisania tego w kodzie skutkuje zbyt długimi nazwami. Co więcej, stale masz do czynienia z tymi „dodatkowymi” informacjami, których potrzebujesz tylko za pierwszym razem, gdy je znajdziesz.

Uważam, że oba obozy mają bardzo ważne argumenty, ale nie należy gorączkowo śledzić jednego obozu, tylko dlatego, że rozwiązuje on jeden problem.

Aby to wykazać, w książce Clean Code kod dzieli się na wiele mniejszych metod, które są wywoływane tylko raz. Metody są tworzone wyłącznie w celu udokumentowania kodu (i łatwiejszego TDD). Powoduje to Piekło funkcji . Kod jest mniej czytelny niż był pierwotnie, a podczas refaktoryzacji nie zastanawiano się nad enkapsulacją kodu wielokrotnego użytku.

Z drugiej strony często widzisz API, w których każda funkcja jest komentowana, tylko dlatego, że „komentarze są dobre”. Rzeczy, które powinny zostać skomentowane, nadal nie są.

„Przykro mi, ale twój facet.”

Zastanawiam się, dlaczego nie lubi komentować: P.

Poważnie, kodowanie jest zbyt wielką sztuką, aby można było zgodnie z prawdą wydać tak szerokie stwierdzenie. Czasami potrzebujesz komentarzy, a czasem więcej i lepiej nazwanych funkcji. Zwykle jedno i drugie.

Spójrz na umiejętne programowanie jako styl ekstremalny.

Krótka, lepsza i poprawna odpowiedź

Pomysł, że dobrze napisany „samodokumentowany kod” jest wszystkim, czego potrzebujesz, to anty-wzór i powinien umrzeć, nawet jeśli zawiera wyjątki od komentarzy wyjaśniających „dlaczego”. To mit, że zawsze możesz napisać cały kod dla dowolnego algorytmu wystarczająco wyraźnego, aby każdy programista mógł na niego rzucić okiem (lub że nie będzie wymagał refaktoryzacji lub czasu organizacyjnego, którego nie masz). Co ważniejsze, częściej niż nie, programiści, którzy myślą, że piszą czysty kod, nie robią tego.

Znacznie lepsza odpowiedź niż komentarze powinna służyć jedynie wyjaśnieniu „dlaczego”, że komentarze powinny:

• wyjaśnij „dlaczego” (oczywiście)
• wyjaśnij „co” w poszczególnych wierszach tylko wtedy, gdy kod jest złożony lub cel jest niejasny i nie może być lub nie warto dalej upraszczać
• wyjaśnij „co” blokom kodu, aby przyspieszyć zrozumienie i zlokalizowanie tego, czego potrzebujesz

Wyjaśnienie, jak wykonać kopię zapasową

Ludzie błędnie myślą, że jedynym powodem, dla którego ludzie używają komentarzy, jest wyjaśnienie, co oznacza wiersz kodu. Prawda jest głównym celem komentowania kodu, aby był szybszyprzejrzeć kod i znaleźć to, czego szukasz. Kiedy wrócę do kodu później lub przeczytam kod innej osoby, na pewno mogę odczytać i zrozumieć część dobrze napisanego kodu - ale czy nie jest to szybsze i łatwiejsze do przeczytania na górze komentarza mówiącego o tym, co robi ta sekcja kodu i pomiń to całkowicie, jeśli nie tego szukam? Po co tam siedzieć i w ogóle wymyślić kod, nawet jeśli jest dobrze napisany, jeśli możesz rzucić okiem na kilka komentarzy i zrozumieć całą funkcję? Dlatego używamy opisowych nazw dla funkcji - nikt nie mówi, że nie muszę używać opisowej nazwy dla mojej funkcji, ponieważ ktoś może po prostu przejrzeć mój czysto napisany kod, aby zobaczyć, co robi.

Na przykład, jeśli przeglądam czyjąś funkcję, czy łatwiej jest przejść wiersz po wierszu przez kod, aby zobaczyć, co robi, lub rzucić okiem na trzy dobrze napisane komentarze w całej funkcji, aby zobaczyć dokładnie, co ta funkcja robi i gdzie robi to?

Kolejnym anty-wzorcem jest nadużywanie funkcji do komentowania kodu. Dobrze nazwane funkcje są ważną częścią dokumentacji kodu, ale czasami programiści oddzielają 2-3 wiersze kodu, które nigdy nie zostaną użyte nigdzie indziej w funkcji do celów dokumentacji. Dlaczego nadużywanie funkcji jest lepsze niż nadużywanie komentarzy? Korzystanie z takich funkcji jest takie samo, jak uwzględnianie instrukcji GOTO - tworzy kod spaghetti, który może być trudny do naśladowania.

Zasadniczo, gdy pracujesz w środowisku korporacyjnym, w którym ludzie stale dzielą się kodem, a ludzie nie zawsze mają czas na doskonalenie swojego kodu, kilka dobrych komentarzy może zaoszczędzić mnóstwo czasu i frustracji. I pamiętaj, że chociaż jesteś guru, który potrafi czytać kod z prędkością światła, prawdopodobnie nie wszyscy w twoim biurze są.

Cóż, musisz także pamiętać o czymś oczywistym lub „dokumentującym” siebie, może nie być dla kogoś innego ... Może kogoś, kto mniej rozumie niektóre funkcje. Więc komentuję prawie wszystko.

Cóż, z kodem samodokumentującym jest to, że w ramach tej funkcji można znaleźć:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

co jest oczywiste, gdy masz nazwę funkcji, ponieważ to tylko dwie linie. Kiedy sprawy stają się bardziej skomplikowane, musisz albo zawijać co kilka wierszy kodu w funkcję o nazwie opisowej, albo w razie potrzeby używać komentarzy .

Nigdy nie rozumiałem, dlaczego powinna to być lub / i materia, zamiast i / i. Tak, uczyń swój kod tak samo dokumentującym, jak to możliwe, i tak, dodaj komentarze do części, które w innym przypadku byłyby raczej niejasne.

Komentarze i samodzielnie udokumentowany czysty kod są różne. Kod polega na tym, jak to robić. Komentarze powinny obejmować część dlaczego , której nie można wyjaśnić kodem, niezależnie od języka. Ponadto, jeśli Twój język jest bardzo ograniczony i nie masz żadnych umów, żadnych specyfikacji statycznych, a nawet żadnych stwierdzeń, komentarze powinny obejmować kwestie graniczne kodu.

W takim przypadku łatwo jest utworzyć funkcję opisową. Ale przeczytałem dużo kodu napisanego przez dobrych programistów, którzy wierzyli, że ich kod sam się dokumentuje, a to, co było dla nich krystalicznie czyste, było dla mnie bardzo mylące.

$ extension = GetFileExtension ($ image_name);

Aby wrócić do twojego przykładu, czy mogę wysłać do niego tablicę nazw obrazów, czy może to tylko jedno zdjęcie? Czy obsługuje jakieś typy plików, czy tylko niektóre z nich? Czy zabezpieczy dla mnie ciąg, czy też muszę to zrobić? Jeśli typ pliku nie istnieje, czy powiadamia mnie?

Oczywiście, trochę to rozciągam. Pamiętam jednak programistę, który wierzył, że audio_bandwidth i video_bandwidth to nazwy samo-dokumentujące; okazało się, że audio musi być wyrażone w bajtach, a wideo w kilobajtach. Zajęło mi dużo czasu, żeby to rozgryźć.

Jedno nie wyklucza drugiego. Nawet jeśli Twój kod jest komentowany przez siebie, czasami możesz potrzebować regularnych komentarzy, aby wyjaśnić, dlaczego twój kod komentujący robi to, co robi.

Nie zgadzam się z tym artykułem i do pewnego stopnia się z tobą zgadzam. Jeśli używasz dobrych nazw metod, dobrych nazw zmiennych i małej metody, które wykonują jedną rzecz, kod powinien być prosty do naśladowania.

Staraj się nie być sprytny, ponieważ sprytny kod jest okropnie czytany i utrzymywany. Słowo kluczowe: zachowaj !

Moim zdaniem komentarze powinny opisywać, dlaczego, a nie co. Pamiętaj, że w tym hipotetycznym idealnym świecie kod jest wystarczająco czysty, aby umożliwić łatwy odczyt, nie musisz wyjaśniać, co robi, ale dlaczego zdecydowałeś się zrobić to w ten lub inny sposób.

Jeśli korzystasz z systemu kontroli źródła, możesz użyć komunikatu zatwierdzenia, aby wszyscy (i ty) wiedzieli, co zrobiłeś w danym momencie, a co ważniejsze, dlaczego. A

Chciałbyś uniknąć pisania komentarzy, tak jak chciałbyś uniknąć jakiejkolwiek dokumentacji. Jeśli chodzi o sam język programowania, wszyscy korzystają z tego samego zestawu słownictwa i składni (prawie).

Jeśli Twoja aplikacja jest przeznaczona dla określonej domeny, zaangażowanie wszystkich osób w ustalenie wspólnego słownictwa może być trudne. Nauczono nas unikać skrótów i obszernego żargonu, ale zamierzam to nazwać

EBITDA

i nie

EquityBeforeInterestTaxesDepreniaAndAmortization

Jeśli nie znasz jednego, prawdopodobnie nie rozumiesz drugiego. Jeśli firma ma jakąś nietypową implementację, komentarz pomógłby następnemu programistowi, który może mieć doświadczenie w domenie, ale nie tej konkretnej firmie (co tylko komplikuje sprawę).

Myślę, że musimy odróżnić dokumentacji i ekspresyjności kodu.

Podczas debugowania lub recenzowania kodu nie czytasz książki. Przez większość czasu chcesz po prostu przeskakiwać od metody do metody i nawiązywać szybkie połączenia w swoim umyśle, aby uzyskać podstawowe zrozumienie tego, co dzieje się w czasie wykonywania. To nie dokumentacja wokół kodu, ale ekspresja podpisów kodu, ich zdolność do bycia wystarczająco znaczącym, abyś mógł je natychmiast zidentyfikować i dodać do własnego wewnętrznego stosu wywołań. W tym momencie nasz mózg (przynajmniej mój działa w ten sposób;)) zwykle traktuje duże bloki komentarzy jako hałas, a nie pomoc. Dlatego też komentarze w jednym wierszu, a nawet lepiej, same opisowe metody i nazwy obiektów są tutaj wystarczające.

Jeśli chcesz „przeczytać książkę” określonej klasy lub funkcji, o wiele lepszym miejscem do tego są testy jednostkowe. Dobrze zaprojektowane testy jednostkowe są z natury odkrywcze i znacznie bardziej dokumentujące (tj. Wyjaśniające, szczegółowe) niż najgrubsze bloki komentarzy, ponieważ zawierają 1 / oczekiwania dotyczące dokładnie tego, co powinien zrobić ten kod i 2 / możliwość sprawdzenia te oczekiwania w stosunku do prawdziwego kodu. Test pozytywny jest sto razy bardziej wiarygodny niż jakikolwiek komentarz w zakresie dokumentacji, ponieważ dowodzi, że to, co twierdzi, jest prawdą.

Niektóre kody nie są po prostu dokumentowane przez siebie i wymagają komentarza od innych ludzi, którzy zrozumieli i przetestowali ten kawałek. Myślę, że to, co mam poniżej, nie wystarczy, aby to zrozumieć.

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}

Zasadniczo wolę pisać kod samo-dokumentujący, z komentarzami, które są niejasne, ponieważ uważam, że większość kodu nie do końca sama się dokumentuje.

Na uniwersytecie uczono nas, jak właściwie przeformułować każdy wiersz kodu w języku angielskim z komentarzem (prawdopodobnie tylko po to, aby nabrać nawyku rozumienia, co właściwie robi kod, zamiast po prostu kopiować / wklejać coś i mieć nadzieję na najlepsze).

Osobiście uważam, że to zaśmieca twój kod, czyniąc go mniej czytelnym niż gdyby były to tylko komentarze lub kod. Jestem programistą w języku C # i jedyne komentarze, które ciągle piszę, to bloki komentarzy typu „potrójny ukośnik”, które są interpretowane z powrotem do dokumentacji IntelliSense. Jeśli czuję się szczególnie winny z powodu określonego sposobu zrobienia czegoś lub wygląda to szczególnie tajemniczo, dam dalsze wyjaśnienie, ale o to chodzi.

IMO: Kod samokontrujący jest kodem, w którym nazwy zmiennych i metod otrzymują nazwy znaczące i kontekstowe, aby opisywały ich cel.

Jeśli wielokrotnie odwiedzałeś kod i nadal nie znalazłeś sposobu, aby wyjaśnić intencję osobie, która zna domenę. Przepisz funkcję. W końcu to nie więcej niż 10-20 linii. Jeśli jest dłużej przepisany, to i tak funkcja jest za długa i to po części dlatego jest nieczytelna :) płukanie-powtarzanie

a w mało prawdopodobnym przypadku nadal nie jest jasne, co robi kod, i pamiętasz, jak poprosić znajomych o pomoc. Więc wszyscy dziękujemy za pomoc w rozwoju Linuksa, ponieważ piszesz kod jądra, prawda? jeśli nie spłucz, powtórz od góry :)

Po prostu nie pisz, że masz komentarze KODUJ je

Sprawdź kod Complete 2nd edition, str. 128-129.

Abstrakcyjne typy danych uratują cię przed tą zagadką. Kod samodokumentujący jest właściwą drogą. Komentarze mogą być przydatne, ale mają

rzeczywiste jednostki, a nie implementacje niskiego poziomu

możesz uniknąć używania komentarzy.

Jedną rzeczą w komentarzach jest to, że piszesz je raz, ale nie widzisz ich po zaimplementowaniu funkcji, widzisz je tylko po zmianie funkcji.

Komentarze są bardzo przydatne, gdy są interpretowane przez IDE w sposób, w jaki działają Delphi 2009+ lub JavaDoc, ale jest to bardziej strukturalny język znaczników, więc w pewnym sensie programujesz swoją dokumentację, która jest bardzo inteligentna.

Wierzę w mantrę, że kod sam się nie dokumentuje, ponieważ możesz być najlepszym programistą na świecie (Ady), a mimo to nie rozumiesz nic o tym, co się dzieje, ale jeśli udokumentujesz, dlaczego i w niewielkim stopniu jak twój kod robi to, co robi, pomożesz sobie i innym w przyszłości.

Komentarze są obowiązkowe. Ponieważ pisząc kod, piszesz dla swoich bieżących potrzeb, ale także dla ludzi w przyszłości, którzy muszą przeczytać Twój kod, dowiedzieć się, wtf, robisz i dlaczego, a następnie jak wprowadzić dla niego modyfikacje.

Jeśli o tym pamiętasz, podczas kodowania / programowania?

Jak mogę to łatwiej zrozumieć i zmodyfikować dla przyszłych programistów tego kodu, nad którym pracuję, to wykonasz dobrą robotę. W przeciwnym razie po prostu utrudnisz innym modyfikowanie kodu i nie wyobrażaj sobie, że nigdy tak się nie stanie, to rzadkie ...

W większości prac musiałem zawsze modyfikować kod innych ludzi, a co najstraszniejsze, źle udokumentowane.

Więc twoim nawykiem myślenia o tym, że kod jest sam, jest po prostu niedokładne.

Jako programiści musimy ćwiczyć samodyscyplinę, która może wydawać się całkowicie niedoświadczona dla programistów, ale musi mieć nawyki, aby uniknąć wszystkich okropnych doświadczeń, jakie mieliśmy z kodem innych ludzi. Lub nawet patrząc na nasz własny kod miesiące, lata później.

Sprawdź http://thedailywtf.com, które mają mnóstwo humorystycznych, ale prawdziwych historii o programistach, którzy po prostu nie dołożyli należytej staranności.