Kod samo dokumentujący vs. Skomentowany kod

22

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?

Phill
źródło
1
@ Péter - przyjrzałem się temu, ale bardziej chciałem uzyskać między nimi osobistą opinię, niż definiować komentarze jako pachnące kodem, czy nie.
Phill
2
Uważam ten artykuł za… straszny do przeczytania. Bardzo obraźliwe.
sevenseacat
@Karpie - Do Did I :(
Phill
3
„Dlaczego jesteś złym programistą PHP” Odpowiedź: Ponieważ programujesz w PHP.
Thomas Eding,
Preferowana metoda polega na użyciu wywołań funkcji do komentowania kodu. Dlaczego nie użyć do tego komentarzy? Funkcje powinny być używane tylko dla kodu wielokrotnego użytku. Osobiście nienawidzę konieczności podążania za czyimś kodem napisanym w ten sposób z tego samego powodu, dla którego oświadczenie GOTO jest złe - tworzy kod spaghetti. Jest to ulepszone przez nowoczesne IDE, ale nie każdy język i programista może używać tych IDE i nadal dezorientuje. Szczerze mówiąc, zgadzam się, że powinieneś komentować fragmenty kodu, które na pierwszy rzut oka nie są jasne - sprawia, że ​​czytanie kodu jest o wiele szybsze i łatwiejsze.
dallin

Odpowiedzi:

46

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.

Péter Török
źródło
Uwielbiam tę książkę :)
Phill
Nadal uważam komentarze za cenne dla wyrażenia zastosowanej strategii oraz tych, którzy zostali odrzuceni (z uzasadnieniem). Zgadzam się, że mikro-komentarze są generalnie bezużyteczne.
Matthieu M.
9
Jednym z moich ulubionych cytatów z Clean Code jest to, że każdy komentarz nie wyraża się w kodzie.
Doval
6
@Doval: Interesująca filozofia, przynajmniej w odniesieniu do komentarzy na temat tego, co robi kod . Z drugiej strony, niektóre z najbardziej użytecznych komentarzy mogą dotyczyć tego, dlaczego kod nic nie robi - pojęcia, którego, moim zdaniem, nie należy oczekiwać od kodu.
supercat
1
Całkowicie się nie zgadzam. Żadna ilość nazw nie będzie w pełni opisywać celu logiki.
Kanion Kolob
65

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

biziclop
źródło
3
+1 Przykład w linkowanym artykule mówi „komentuj w każdej sytuacji, w której cel kodu, który napisałem, nie jest od razu widoczny”. - Głupotą jest wierzyć, że kod sam w sobie może komunikować cel , ponieważ same maszyny nie mają pojęcia celu. Counter example: Mamy błędy w prawie każdym oprogramowaniu, jakie kiedykolwiek napisano, to jest truizm. Jeśli komputer zrozumiałby cel ( dlaczego ), po prostu odmówiłby zrobienia czegoś innego niż to, co zamierzaliśmy, zamiast posłusznego odtworzenia tego, co / kiedy / jak / gdzie doprowadziło to do błędu.
David Meister
Cały kod wewnątrz funkcji powinien tam być, aby spełnić cel funkcji, tzn. Co robi, np. Napisać tekst do pliku, funkcję „writeTo (tekst ciągu, plik pliku)”. Jeśli jakiś kod ma inny cel, np. Sprawdzenie warunków wstępnych, na przykład sprawdzenie, czy plik istnieje ORAZ nie jest to oczywiste, być może lepszym pomysłem niż komentarz jest napisanie nowej funkcji, np. „CheckWritable (plik pliku)”. Jakość kodu nie jest dogmatyczną listą kontrolną, ale jeśli potrzebuje komentarzy, to zły znak, a „dlaczego” nie są dobrym powodem, aby ich potrzebować . Dlaczego kurczak przeszedł przez ulicę?
Trylks,
2
@Trylks To działa w niektórych przypadkach, ale nie dla wszystkich. Wyobraź sobie taki scenariusz: for (int i = 0; i < length/2;i++) { //if length is odd, the middle element should stay in place. Otóż ​​nie jest to ani oczywiste z celu funkcji zamykającej, ani nie można jej rozdzielić na własne funkcje. Jeśli pozostawisz to bez komentarza, to wyraźnie złe. Więc dodajesz komentarz, aby wyjaśnić swoje zamiary.
biziclop,
2
@Trylks Poza tym, nawet jeśli weźmiemy twój przykład, bierzesz pod uwagę metodę i nazywasz ją świetnie. Teraz wszystko, co musisz wyjaśnić, to dlaczego musisz sprawdzić, czy plik jest zapisywalny. :)
biziclop,
38

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.

Wieża
źródło
Byłem tam, zrobiłem to. „Kod mniej czytelny” należy przekształcić w kod, który dobrze czyta. Znajomość języka tak naprawdę się nie liczy: jeśli nie znasz składni, powinieneś się jej najpierw nauczyć - szczerze mówiąc, to podstawa bycia profesjonalistą. Próba nadrobienia strasznego kodu poprzez dodawanie komentarzy nie jest dobrym pomysłem. Komentarze nigdy nie powinny próbować opisywać działania kodu. (Ogólny) komentarz jest uzasadniony tylko wtedy, gdy musisz powiedzieć, dlaczego, a nie co . Cała reszta to tylko hałas i niepotrzebne dodatkowe rzeczy do utrzymania.
Powerslave,
PS, wiem, że trochę „zombie” :) Przepraszam za to
Powerslave,
Aby uniknąć nieporozumień, mówię o zwykłym przypadku, gdy nie jesteś zmuszony do pisania złego kodu na podstawie wymagań biznesowych (np. Wyjątkowa wydajność lub dopasowanie do ograniczonej pamięci). W innych (rzadkich) przypadkach nie ma innej opcji niż pozostawienie komentarza, co nieco zmniejsza ciężar następnej ofiary.
Powerslave,
19

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

Steven Jeuris
źródło
1
@Steven - „Z drugiej strony często widzisz interfejsy API, w których każda funkcja jest komentowana, tylko dlatego, że„ komentarze są dobre ”. Rzeczy, które powinny były zostać skomentowane, nadal nie są.” Ugh, tak frustrująco prawdziwe!
dss539
To bardzo dobra odpowiedź! Jedną rzeczą, jeśli nie masz nic przeciwko, czytelność komentarzy: osobiście nie wierzę, że komentarze są bardziej czytelne. My, jako programiści, zwykle myślimy w kodzie źródłowym, szczególnie w „trybie kodowania”. W takich momentach niejasność zwykłego ludzkiego języka jest zwykle bardziej rozproszeniem niż pomocą.
Powerslave,
5

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

wegetarianin
źródło
Tak. Mam na myśli, że jeśli Donald Knuth uważa, że ​​nie tylko potrzebujesz komentarzy, ale czasem potrzebujesz ich rozdziałów , pomyślałbym co najmniej dwa razy, zanim się nie zgodzę.
PeterAllenWebb
3

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

dallin
źródło
Nienawidzę tego, kiedy ludzie głosują i nawet nie komentują dlaczego. Czy w ogóle przeczytałeś cały post? Co tam nie jest proste i prawdziwe? Z czym się nie zgadzasz? Wydaje mi się, że ludzie są tak pochłonięci swoim pomysłem lub tym, co czytają, że nawet o tym nie myślą i głosują od razu za wszystkim, co nie podziela ich opinii.
dallin
3
Zakładam, że dzieje się tak dlatego, że wprost odrzucasz i nazywasz antypattern czymś, co prawie powszechnie uznaje się za słuszne. Z pewnością uważam, że posuwasz się za daleko. Przeważnie nie wyobrażam sobie tak ufnych komentarzy, jak się wydaje. Jeśli na ślepo czytasz komentarze, a nie kod, komentarze mogą być niepoprawne i nieaktualne i nigdy się nie dowiesz. To podstawa używania funkcji jako dokumentacji. Zgadzam się, że nie powinieneś mieć zbyt wielu funkcji w jednym miejscu, chociaż rozwiązaniem tego na pewno nie jest zastąpienie ich komentarzami.
Mag
@Magus Dzięki za komentarz. Zakładam, że odnosiłeś się do mojego mówienia o używaniu funkcji jako dokumentacji. Powtarzając to, wydaje mi się, że źle sformułowałem, że brzmię tak, jakby w ogóle chciałem używać funkcji do tego celu (w przeciwieństwie do nadużywania funkcji do tego celu) było złe. Wyczyściłem ten akapit, aby wyjaśnić moje pierwotne zamiary. Myślę o zaufaniu do komentarzy, jeśli komentarz staje się przestarzały, zwykle jest to znak, że komentujesz zbyt wąską część kodu - że komentujesz implementację, a nie zamiar.
dallin
but isn't it faster and easier to read the comment at the top saying what that section of code does and skip it altogether if it's not what I'm looking forNazywa się to „nazwą metody / funkcji”. Jeśli masz blok kodu, który nie ma nazwy, ale jest na tyle długi, że nie możesz go przejrzeć jednym rzutem oka, być może problem leży w tym.
biziclop
1
@biziclop Nadgodziny Uwierzyłem, że ten argument jest głównie semantyką, a w praktyce nasz kod wyglądałby podobnie. To powiedziawszy, zakładając, że blok kodu nie jest używany w więcej niż jednym miejscu, nie widzę różnicy między blokiem kodu z krótkim komentarzem opisowym u góry a blokiem kodu z krótką nazwą funkcji opisowej na Top. Są takie same, tyle że nie ma spacji. Mogą być zarówno złe, jak i nieaktualne. Jedyną różnicą, którą naprawdę widzę, jest to, że kod jest łatwiejszy do odczytania z komentarzem, ponieważ nie musisz podążać za wywołaniem funkcji w oddzielnej lokalizacji.
dallin
2

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.

użytkownik6791
źródło
1
Czy możesz podać przykład? Mam na myśli podany przykład w moim pierwotnym pytaniu. „GetFileExtension” jaki jest sens komentarza „Pobiera rozszerzenie danego pliku”? Metoda opisała już, co powinno znaleźć się w komentarzu. Jeśli metoda nosi nazwę „GetExtension”, komentarz pomoże wyjaśnić, co ma zrobić, ponieważ metoda nie wyjaśnia się sama.
Phill
+1 To pytanie, które znają Twoi odbiorcy. Kto może korzystać z tej funkcji? Jak możesz im pomóc? Jaka będzie Twoja pomoc? Czy warto teraz poświęcić trochę czasu, aby dodać komentarz? Itd. Itd. Itd.
PeterAllenWebb
2
@PeterAllenWebb: W ogóle nie ma sensu do tego komentarza. Nie oznacza to wcale, że funkcja nie powinna być komentowana; powinno. Czy „rozszerzenie” zawiera kropkę, czy nie? Jaka jest wartość zwracana "foo"? ( null?? "") Dla "foo."? Czy przekazanie nullspowoduje wyjątek, czy funkcja coś zwróci (być może null)?
TJ Crowder
2

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.

Joris Meys
źródło
Tak. Myślę, że musisz być „przeszkolony”, aby myśleć, że powinien to być jeden lub drugi, a nie oba.
PeterAllenWebb
2

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.

Logika SK
źródło
Zakładając, że wszystko jest uzasadnione, należy je skomentować?
JeffO
Tak, dokładnie. Dlatego uważam, że najlepszym sposobem na skomentowanie twojego kodu jest umiejętne pisanie.
SK-logic
1

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źć.

Niphra
źródło
5
Często to rozciągasz. Funkcja pobiera rozszerzenie nazwy pliku. Nic dodać nic ująć. Jego nazwa mówi, czy bierze tablicę czy nie (oczywiście nie). Nie mogę wymyślić metody, która opierałaby się na typie pliku, aby uzyskać rozszerzenie. Zabezpieczenie łańcucha jest jedynym, które może zostać włączone, ale nigdy bym się tego nie spodziewał, ponieważ jak wie każdy programista w PHP: wszystkie dane wejściowe użytkownika są podejrzane, więc zabezpiecz je przed użyciem.
Matt Ellen
2
@Matt: „Wyraźnie nie” oznacza, że ​​nie przeprowadzasz konserwacji zbyt często. Wyrażenie się w ten sposób oszczędza później wiele drapania w głowie (i RTFSource), a także dokumentuje to, czego oczekiwał oryginalny autor . Czy to w komentarzu, czy w długiej nazwie funkcji, nie jest prawie tak ważne.
Donal Fellows
Być może przykład był zły do ​​użycia w tym pytaniu, nie dotykałem PHP od około 7 lat, robiłem C # i trochę Java, więc jestem przyzwyczajony do posiadania IDE, które mówi mi, że typ zwrócił lub deklarowanie typów.
Phill
1
@Donal Fellows: mówi plik, liczba pojedyncza. Co jest w tym dwuznacznego? To jest całkowicie jednoznaczne.
Matt Ellen
4
Fakt, że obecnie jest 7 odpowiedzi od 4 osób dyskutujących na temat oczywistości pojedynczego wywołania funkcji, sugeruje mi, że musisz użyć komentarzy . Podkreślono także fakt, że dokładne nazewnictwo jest formą samą w sobie.
Ant
1

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.

gablin
źródło
Myślę, że takie jest moje zdanie, które brzmiało: „kod powinien mieć charakter opisowy i przeważnie nie wymagać komentarza, chyba że kod nie może opisywać się sam”. Jeśli piszesz kod, który jest dobrze napisany, nie wyjaśnia w pełni jego intencji, to komentarze pomagają uczynić kod bardziej opisowym.
Phill
Kod nigdy nie może wyjaśnić jego celu. Kiedy widzisz młot, nie możesz zrozumieć, po co to jest - czy to do rozbijania czaszek, czy po prostu do kucia surowego żelaza.
SK-logic
1
@ SK-logic:public <T> void hit(T item);
Michael K
@Michael - dokładnie. Jak użytkownik się zorientuje, jakie kategorie obiektów można i należy wbijać? Nawet przy znacznie lepszym systemie typowania nie zawsze jest jasne, jaki zakres możliwych zastosowań faktycznie planuje programista.
SK-logic
1

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

Sergio
źródło
1

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

JeffO
źródło
1

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

guillaume31
źródło
1

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;
}
Praca
źródło
1

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.

Abbafei
źródło
0

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.

James Love
źródło
0

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

Rune FS
źródło
0

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.

Peter Turner
źródło
0

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.

Coyote21
źródło
0

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.

Crosenblum
źródło