„Komentarze to zapach kodu” [zamknięte]

100

Mój współpracownik uważa, że każde użycie komentarzy w kodzie (tj. Nie metoda w stylu javadoc lub komentarze do klasy) to zapach kodu . Co myślisz?

Fishtoaster
źródło
44
Będę głosować za odpowiedzią, która mówi „nie”.
Nicole,
2
@Rezesis To zapach boskości.
ixtmixilix
107
Twój współpracownik dokonał szerokiego uogólnienia, co automatycznie oznacza, że ​​się myli. :)
Alex Feinman
5
@Mongus, nie zgadzam się. Komentarze w twoim przykładzie są złe nie dlatego, że są komentarzami, ale dlatego, że ZBYT są zbliżone do kodu, który następnie się zmienia. Powinny powiedzieć DLACZEGO, a nie CO .
5
@Alex, czyż nie jest to szerokie uogólnienie, które jest zatem błędne (co powoduje, że i tak się nie myli)?

Odpowiedzi:

167

Tylko jeśli komentarz opisuje, co robi kod.

Gdybym chciał wiedzieć, co dzieje się w metodzie lub bloku, przeczytałbym kod. W każdym razie mam nadzieję, że wszyscy programiści pracujący nad danym projektem byli przynajmniej na tyle obeznani z językiem programowania, aby przeczytać to, co jest napisane i zrozumieć, co robi.

W niektórych przypadkach skrajnej optymalizacji możesz używać technik, które utrudniają komuś śledzenie tego, co robi Twój kod. W takich przypadkach można i należy wykorzystać komentarze, aby nie tylko wyjaśnić, dlaczego masz takie optymalizacje, ale także to, co robi kod. Dobrą zasadą byłoby, aby ktoś inny (lub wiele innych osób) zapoznał się z językiem implementacji i spojrzeniem projektu na Twój kod - jeśli nie rozumieją zarówno przyczyny, jak i sposobu, powinieneś skomentować zarówno dlaczego, jak i jak.

Jednak w kodzie nie jest jasne, dlaczego coś zrobiłeś. Jeśli podejmiesz podejście, które może nie być oczywiste dla innych, powinieneś mieć komentarz wyjaśniający, dlaczego podjąłeś decyzje, które podjąłeś. Podejrzewam, że możesz nawet nie zdawać sobie sprawy, że komentarz jest potrzebny dopiero po czymś takim jak przegląd kodu, gdzie ludzie chcą wiedzieć, dlaczego zrobiłeś X zamiast Y - możesz zapisać swoją odpowiedź w kodzie dla wszystkich, którzy na nią patrzą w przyszłości.

Najważniejszą rzeczą jest jednak zmiana komentarzy podczas zmiany kodu. Jeśli zmienisz algorytm, pamiętaj, aby zaktualizować komentarze, dlaczego użyłeś algorytmu X zamiast Y. Komentarze stale są jeszcze większym zapachem kodu.

Thomas Owens
źródło
8
Zgadzam się z tą odpowiedzią w stosunku do komentarzy, ale widziałem ją również jako usprawiedliwienie braku dokumentacji, co jest błędne. Czytanie kodu jest czasem uciążliwe. Nie powinno mieć spojrzeć na kod dla metody, aby dowiedzieć się, co robi ta metoda. Powinieneś być w stanie zrozumieć to na podstawie nazwy i uzyskać więcej szczegółowych informacji z dokumentów. Podczas czytania kodu często musisz przełączać się z klasy do klasy i od pliku do pliku. Jest to szczególnie problem w dynamicznych językach, w których napisanie IDE, które może to wszystko obsłużyć, nie jest trywialne.
davidtbernal
1
W każdym razie czasami musisz również skomentować JAK, jeśli jest skomplikowany (szczególnie, jeśli jest zoptymalizowany lub innego rodzaju nietrywialne operacje). Jeśli muszę poświęcić więcej niż 5 minut na przeczytanie jednego bloku kodu, aby zrozumieć, co on robi, może być dość frustrujące ...
Khelben
3
„Tylko jeśli komentarz opisuje, co robi kod”. Lub jeśli komentarz opisuje, co robił kod; kod się zmienił, ale komentarz się nie zmienił.
Bruce Alderman,
1
Jak sprawdzasz, czy Twój komentarz jest poprawny? Dlaczego nie napisać komentarza jako testu? Każdy przyszły opiekun może wykorzystać test jako weryfikowalną dokumentację kodu. Jeśli komentarz ma coś wspólnego z wykonaniem kodu, to coś / musi / być asertywne. Jeśli komentarz nie ma nic wspólnego z wykonaniem kodu, to co robi w kodzie, w którym będą patrzeć tylko programiści?
flamingpenguin
2
@ back2dos, jeśli często wymiotujesz podczas czytania kodu innych osób, cieszę się, że nie udostępniamy biur ...
110

Jest to szczególnie irytujące, gdy słyszę, że spędziłem trochę czasu w ten weekend, patrząc na bardzo dobrze nazwany, bardzo czysty, niezakomentowany kod implementujący algorytm badawczy (taki, który nie został opublikowany). Znam go na wysokim poziomie, facet siedzący obok mnie był wynalazcą, a kod został napisany kilka lat temu przez kogoś innego. Ledwie mogliśmy to zrobić.

Twój współpracownik nie ma oczywiście wystarczającego doświadczenia.

Paul Nathan
źródło
16
Jestem ciekawy „dobrze nazwanego, bardzo czystego, nieskomentowanego kodu”, który jest trudny do naśladowania. Każdy kod, który sklasyfikowałbym jako taki, był bardzo łatwy do naśladowania. Na pewno nie posunąłbym się tak daleko, że „Twój współpracownik nie ma wystarczającego doświadczenia, oczywiście”.
Liggy
8
@Liggy: Chciałbym. To algorytm badawczy, a nie aplikacja biznesowa.
Paul Nathan
9
Kiedyś miałem kawałek kodu, w którym trzeba było wypełnić pola w obiekcie kolumny bazy danych (podmiot zewnętrzny) w „złej” kolejności (zdefiniowanej przez „logikę” procesu i nasze standardy kodowania) - zrób to w kolejności, w jakiej normalnie użyłby i to by się zawiesiło. Żadna ilość odczytanego kodu nie mogła ci tego powiedzieć, więc pozytywnie, absolutnie musiał mieć komentarz - i nie był to zapach, przynajmniej nie w kodzie, nad którym mieliśmy kontrolę (co jest dolną linią). Całkowity i całkowity brak komentarzy to zarówno zapach, jak i złe komentarze.
Murph
29
Matematyka, matematyka, matematyka. Nie każdy kod implementuje trywialny klej IoC i „cena * ilość”. Złożonej matematyki nie da się magicznie wyjaśnić.
bmargulies
4
@Liggy, kod implementujący złożone struktury danych może być całkowicie niezrozumiały bez obszernej dokumentacji.
75

Komentarze powinny wyjaśniać dlaczego, a nie jak.

Howkomentarze typu są zazwyczaj lepiej rozpatrywane przy użyciu refaktoryzacji. Osobiście zwykle unikam komentarzy na rzecz refaktoryzacji.

Przed:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

po:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)
Sam Saffron
źródło
26
Zgadzam się z tym, dlaczego nie jak części, a twoje refaktoryzacja działa w tym przykładzie, ale przy bardziej złożonym kodzie żadna ilość zmiany nazwy / refaktoryzacji zmiennej / funkcji nie będzie miała idealnego sensu, a komentarze będą tam nadal potrzebne.
GSto
3
Dobry przykład, ale dlaczego system działa z centami w przeciwieństwie do dolarów? To pytanie staje się istotne w systemach finansowych, w których może pojawić się waluta ułamkowa.
rjzii
3
@Stuart nazwa funkcji powinna powiedzieć, co robi.
Alb
3
@GSto, nie mogłem się nie zgodzić. Jeśli kod jest złożony, należy go podzielić na mniejsze metody / funkcje o odpowiednich nazwach opisujących akcję.
CaffGeek
1
Zakładasz, że masz pełną kontrolę nad bazą kodu.
LennyProgrammers
32

Ogłaszam, że twój współpracownik jest heretykiem! Gdzie są moje płonące heretyki?

Obsesyjne komentowanie jest złe i powoduje ból głowy, a komentarze nie zastępują dobrze nazwanych metod, klas, zmiennych itp. Ale czasami wyjaśnianie, dlaczego coś takiego jest, może być niezwykle cenne dla biednego idioty, który musi utrzymywać kod za sześć miesięcy - szczególnie, gdy ten biedny idiota kończy na tobie.

Kilka faktycznych komentarzy z kodu, nad którym pracuję:


    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

BlairHippo
źródło
7
+1 za miłe komentarze. Żadna ilość kodu nie jest w stanie powiedzieć „Jeśli tak się stanie, ktoś popieprzył definicje bazy danych”.
DistantEcho
9
@Niphra, cóż, moglibyśmy rzucić SomebodyScrewedAroundWithDatabaseException...
@ Thorbjørn +1, Jeśli kod wie, co jest nie tak, do cholery, zgłoś to. Klienci wsparcia technicznego mogą prawdopodobnie ponownie załadować bazę danych i uniknąć wezwania serwisu.
Tim Williscroft,
@Tim, ponieważ klienci mogą to zobaczyć, bardziej neutralne nazewnictwo może być właściwe.
3
Jasne, pamiętaj: nigdy nie używaj głupich nazwisk. Klient zawsze je zobaczy.
Tim Williscroft,
29

Idealnie byłoby, gdyby kod był tak dobrze zakodowany, aby mógł być auto-objaśniający. W prawdziwym świecie wiemy, że również bardzo wysokiej jakości kod wymaga czasem komentarza.

To, czego absolutnie powinieneś unikać, to „redundancja kodu komentarza” (komentarze, które niczego nie dodają do kodu):

i++; // Increment i by 1

Następnie, jeśli istnieje dobry (i utrzymany / wyrównany) projekt i dokumentacja kodu, komentowanie jest jeszcze mniej przydatne.

Ale w niektórych okolicznościach komentarze mogą być dobrą pomocą w czytaniu kodu:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

Nie zapominaj, że musisz utrzymywać i synchronizować także komentarze ... nieaktualne lub błędne komentarze mogą być strasznym bólem! I z reguły zbyt wiele komentarzy może być objawem złego programowania.

Lorenzo
źródło
2
Dobra konwencja nazewnictwa i dobrze skonstruowany kod pomogą Ci zmniejszyć liczbę komentarzy. Nie zapominaj, że każdy dodany wiersz komentarzy to nowy wiersz do utrzymania !!
Gabriel Mongeon,
81
Nienawidzę, kiedy ludzie używają tego drugiego przykładu w twoim pytaniu. } //end whileoznacza tylko, że początek pętli while jest tak daleko, że nawet jej nie widzisz, i nie ma żadnych wskazówek, że kod, który oglądasz, znajduje się w pętli. Ciężkie refaktoryzacja powinna być poważnie preferowana w stosunku do komentarzy na temat struktury kodu.
Carson Myers,
4
@Carson: chociaż utrzymywanie krótkich bloków jest dobrze znaną zasadą, nie oznacza to, że zawsze możemy je zastosować.
Wizard79
4
@Carson: Jeden z projektów, nad którymi pracuję, nie ma wystarczającego przeglądu kodu, co doprowadziło do zbioru stron JSP o cyklicznej złożoności „OMFG po prostu zabij siebie”. Refaktoryzacja cholernych rzeczy oznacza dni pracy, które trzeba spędzić gdzie indziej. Te } // end whilekomentarze mogą uratować życie.
BlairHippo
11
@BlairHippo: „Zapach kodu [A] to jakikolwiek objaw w kodzie źródłowym programu, który może wskazywać na głębszy problem”. Oczywiście komentarz jest ratunkiem życia, ale pętla OMGWTF to wspomniany „głębszy problem”, a konieczność oszczędzania życia jest wyraźnym wskaźnikiem;)
back2dos
26

Kategoryczne zdefiniowanie metody lub procesu jako „zapachu kodu” jest „zapachem gorliwości”. Termin ten staje się nowy „uważany za szkodliwy”.

Pamiętaj, że wszystkie tego rodzaju rzeczy mają być wytycznymi.

Wiele innych odpowiedzi daje dobrą radę, kiedy uzasadnione są komentarze.

Osobiście używam bardzo niewielu komentarzy. Wyjaśnij cel nieoczywistych procesów i pozostaw sporadyczną groźbę śmierci każdemu, kto może rozważać samodzielną zmianę rzeczy, która wymagałaby tygodni tuningu.

Przeredagowanie wszystkiego, dopóki przedszkolak nie zrozumie, że prawdopodobnie nie jest to wydajne wykorzystanie twojego czasu i prawdopodobnie nie będzie działać tak dobrze, jak bardziej zwięzła wersja.

Komentarze nie wpływają na czas działania, więc jedynym negatywnym problemem do rozważenia jest konserwacja.

Rachunek
źródło
8
Myślałem, że „anty-wzór” to nowy „uważany za szkodliwy”. Zapach kodu to coś, co wymaga dokładniejszej analizy w celu ewentualnego wyczyszczenia.
Jeffrey Hantin
1
Nie zgadzam się, że anty-wzór również się kwalifikuje. Oba przyzwyczajają się w ten sposób, a zamiast zapachu stosuje się antyrefleksję, gdy konstrukcja jest na tyle złożona, że ​​jest to oczywiście celowy wybór. W obu przypadkach nie zgadzam się z koncepcją, że istnieje absolutne źródło poprawności w tych sprawach.
Bill
4
+1 za „Refaktoryzację wszystkiego, dopóki przedszkolak nie zrozumie, że to nie jest wydajne wykorzystanie twojego czasu i prawdopodobnie nie będzie działać tak dobrze, jak bardziej zwięzła wersja”.
Earlz
23

W niektórych przypadkach żadna ilość dobrego nazewnictwa, refaktoryzacji itp. Nie może zastąpić komentarza. Spójrz na ten przykład z prawdziwego świata (językiem jest Groovy):

  response.contentType="text/html"
  render '{"success":true}'

Wygląda dziwnie, prawda? Prawdopodobnie błąd kopiowania-wklejenia? Woła o poprawkę?

Teraz to samo z komentarzami:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler
użytkownik 281377
źródło
function prime_extjs_uploadform () {response.contentType = 'text / html'; render „{„ sukces ”: prawda}”; } prime_extjs_uploadform ();
DrPizza,
23

Podstawową kwestią jest tutaj znaczenie terminu „zapach kodu”.

Myślę, że wiele osób (łącznie z tobą) rozumie zapach kodu jako coś bliskiego błędu lub przynajmniej coś, co należy naprawić. Być może myślisz o tym jako o synonimie „anty-wzorca”.

To nie jest znaczenie tego terminu!

Metafora zapachu kodu pochodzi z Wiki Wards i podkreślają:

Zauważ, że CodeSmell to wskazówka, że ​​coś może być nie tak, a nie pewność. Idealnie dobry idiom można uznać za CodeSmell, ponieważ często jest niewłaściwie używany lub ponieważ istnieje prostsza alternatywa, która działa w większości przypadków. Nazywanie czegoś CodeSmell nie jest atakiem; to po prostu znak, że uzasadnione jest bliższe spojrzenie.

Co to znaczy, że komentarze są zapachem kodu: oznacza to, że kiedy zobaczysz komentarz, powinieneś zatrzymać się i pomyśleć: „Hmmm, wyczuwam wskazówkę, że coś można poprawić”. Być może możesz zmienić nazwę zmiennej, wykonać „metodę wyodrębniania” - refaktoryzacja - a może komentarz jest w rzeczywistości najlepszym rozwiązaniem.

To właśnie oznacza, że ​​komentarze mogą mieć zapach.

EDYCJA: Właśnie natknąłem się na te dwa artykuły, co wyjaśnia to lepiej niż ja:

Rasmus Faber
źródło
2
Jestem oszołomiony, że odpowiedź zajęła 2 miesiące. Pokazuje, jak powszechne jest nieporozumienie tego terminu.
Paul Butcher,
Ogólne twierdzenie o sprawie jest nadal błędne. Nie mówicie: „Widzę kod z komentarzem. To zły znak”.
Stuart P. Bentley,
1
@Stuart: Patrzysz na dwa fragmenty kodu, oba z odpowiednimi poziomami komentarzy. (Ten problem nie dotyczy odpowiedniej liczby komentarzy, dotyczy tego, jak oceniasz kod na podstawie liczby komentarzy.) Jeden nie ma komentarzy, drugi ma mnóstwo. Na co patrzysz bliżej? - Komentarze są oznaką, że kod jest skomplikowany i subtelny, a przez to bardziej prawdopodobny.
David Schwartz,
To jest poprawna odpowiedź.
vidstige
21

Myślę, że zasada jest dość prosta: wyobraź sobie, że twój nieznajomy widzi twój kod. Twój kod prawdopodobnie będzie Ci obcy za 5 lat. Spróbuj zminimalizować wysiłek umysłowy, aby zrozumieć swój kod dla tego nieznajomego.

LennyProgrammers
źródło
8
+1 Każdemu twórcy, który nie pracował nad jednym projektem wystarczająco długo, aby tego doświadczyć, wierz mi, że to się stanie. Za każdym razem, gdy uczę się tego na własnej skórze i muszę ponownie nauczyć się własnego kodu, nie pozwalam sobie popełniać tego samego błędu dwa razy i komentować go, zanim przejdę do czegoś innego.
Nicole,
Nie, powinieneś wyobrazić sobie psychopatę, który wie, gdzie mieszkasz: czy z przyjemnością utrzymają Twój kod?
Richard
4
Regularnie zostaję psychopatą, gdy widzę nieczytelny kod.
LennyProgrammers
3
5 lat? Więcej jak 5 minut. ;)
Alex Feinman
11

Dobrym pomysłem na właściwe komentarze jest rozpoczęcie pisania komentarzy.

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

Pozwala to łatwo wyodrębnić metody, aby nawet pozbyć się komentarzy,
po prostu pozwól kodowi powiedzieć te rzeczy ! Zobacz, jak to jest przepisane (wytnij / wklej) w bardzo przyjemny sposób:

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

W przypadku rzeczy, których nie można rozdzielić, po prostu nie wyodrębniaj metod i wpisz kod pod komentarzami.

To, co uważam za użyteczny sposób ograniczania komentarzy do minimum, naprawdę bezużyteczne jest komentowanie każdej linii ... Dokumentuj tylko jedną linię, jeśli dotyczy inicjalizacji wartości magicznej lub tam, gdzie ma to sens.

Jeśli parametry są używane zbyt często, powinni być prywatnymi członkami twojej klasy.

Tom Wijsman
źródło
1
To jest to, co robie. Jeśli uważasz, że potrzebujesz komentarzy, mogę polecić to jako zamiennik.
bzlm
10

Myślę, że odpowiedź brzmi: „To zależy”. Komentowanie kodu, aby skomentować kod, to zapach. Komentowanie kodu, ponieważ używasz niejasnego algorytmu, który jest o rząd wielkości, szybciej oszczędza programistom konserwacji (zwykle mnie 6 miesięcy po napisaniu go) pół dnia przeszukiwania kodu w celu ustalenia, co robi.

Brandon
źródło
10
// Dear me in the future. Please, resolve this problem.

lub

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.
Zzz
źródło
Ach, serdeczne prośby do przyszłego siebie.
Anthony Pegram
8

Komentarze do kodu zdecydowanie nie są „zapachem kodu”. Przekonanie to zazwyczaj wynika z faktu, że komentarze mogą stać się nieaktualne (nieaktualne) i mogą być trudne do utrzymania. Jednak dobre komentarze wyjaśniające, dlaczego kod robi coś w określony sposób, mogą (i zwykle są) ważne dla konserwacji.

Dobre komentarze ułatwiają zrozumienie tego, co robi kod i, co ważniejsze, dlaczego robi to w określony sposób. Komentarze mają być czytane przez programistów i powinny być jasne i precyzyjne. Komentarz, który jest trudny do zrozumienia lub niepoprawny, nie jest dużo lepszy niż brak komentarza.

Dodanie jasnych i precyzyjnych komentarzy do kodu oznacza, że ​​nie musisz polegać na pamięci, aby zrozumieć „co” i „dlaczego” w części kodu. Jest to najważniejsze, gdy spojrzysz na ten kod później lub ktoś inny musi na niego patrzeć. Ponieważ komentarze stają się częścią tekstowej zawartości twojego kodu, powinny być zgodne z dobrymi zasadami pisania, oprócz tego, że są napisane jasno.

Aby napisać dobry komentarz, powinieneś dołożyć wszelkich starań, aby udokumentować cel kodu (dlaczego, a nie jak) oraz wskazać rozumowanie i logikę stojącą za kodem tak jasno, jak to możliwe. Idealnie, komentarze powinny być pisane w tym samym czasie, w którym piszesz kod. Jeśli zaczekasz, prawdopodobnie nie wrócisz i nie dodasz ich.

Sams Teach Your Visual C # 2010 w ciągu 24 godzin , s. 348–349.

Scott Dorman
źródło
1
Komentarze mogą stać się nieaktualne, ale dotyczy to wszystkiego, co nie jest weryfikowane przez kompilator lub test jednostkowy, na przykład znaczenia nazw klas, funkcji i zmiennych.
LennyProgrammers,
@ Lenny222: Tak, komentarze mogą stać się nieaktualne ... co zwykle wskazuje na leniwych programistów. Jeśli komentarz opisuje, dlaczego podjęto decyzję, dlaczego kod używa określonego algorytmu do obliczeń, lub opisuje, jak działa kod, to nie ma powodu, aby komentarz stał się nieaktualny poza tym, że ktoś zmienił implementację i nie zaktualizował komentarza odpowiednio - co jest równoważne z lenistwem.
Scott Dorman,
2
Zgadzam się. Chodzi mi o to, że istnieje ryzyko starzenia się, tak. Ale kiedy mam funkcję doBar () i po 3 latach nie „robi to bar”, ale „robi bar i foo z wyjątkiem środy”, wtedy znaczenie funkcji może stać się nieaktualne. I nazwy zmiennych. Ale mam nadzieję, że nikt nie bierze tego z powodu, aby nie nadawać funkcjom i zmiennym znaczących nazw.
LennyProgrammers,
6

Jeśli kod został napisany w określony sposób, aby uniknąć problemu w bibliotece (zarówno w bibliotece innej firmy, jak i bibliotece dostarczanej z kompilatorem), warto go skomentować.
Sensowne jest także komentowanie kodu, który należy zmienić w przyszłych wersjach lub podczas korzystania z nowej wersji biblioteki lub na przykład podczas przechodzenia z PHP4 do PHP5.

kiamlaluno
źródło
6

Nawet najbardziej dobrze napisana książka prawdopodobnie zawiera tytuły wstępu i rozdziałów. Komentarze w dobrze udokumentowanym kodzie są nadal przydatne do opisywania pojęć wysokiego poziomu i wyjaśniania, w jaki sposób kod jest zorganizowany.

hojny
źródło
Komentarze tego rodzaju dają ładne wskazówki wizualne, więc nie musisz czytać każdej linii, aby znaleźć początek szukanej sekcji. Jak mawiał mój dziadek „wszystko z umiarem”.
Blrfl
4

Godnym uwagi jest anty-wzór:

Mam wrażenie, że zamiast dokumentacji plików często stosuje się preambuły licencji FLOSS . GPL / BSDL tworzy fajny tekst wypełniający, a potem rzadko widzisz inny blok komentarza.

Mario
źródło
4

Nie zgadzam się z pomysłem, że pisanie komentarzy w celu wyjaśnienia kodu jest złe. To całkowicie ignoruje fakt, że kod zawiera błędy. Może być jasne, co robi kod bez komentarzy. Jest mniej prawdopodobne, aby być jasne, jaki kod jest niby zrobić . Bez komentarzy, skąd wiesz, czy wyniki są nieprawidłowe, czy są nieprawidłowo wykorzystywane?

Komentarze powinny wyjaśniać zamiar kodu, aby w przypadku pomyłki ktoś czytający komentarze + kod miał szansę go znaleźć.

Zazwyczaj piszę wbudowane komentarze przed napisaniem kodu. W ten sposób jasne jest, co próbuję napisać, i zmniejsza zagubienie się w algorytmie, nie wiedząc naprawdę, co próbujesz zrobić.

Danny Tuppeny
źródło
1
Testy jednostkowe bardzo pomagają ustalić, czy wyniki są błędne. Jeśli czytasz jakiś kod i myślisz, że robi X, podczas gdy w rzeczywistości robi Y, to możliwe, że kod nie jest napisany w wystarczająco czytelny sposób. Nie jestem pewien, co masz na myśli mówiąc, że wyniki są używane nieprawidłowo. Komentarz nie ochroni Cię przed dziwnym wykorzystaniem przez Ciebie kodu.
Adam Lear
„Jeśli czytasz jakiś kod i myślisz, że robi X, podczas gdy w rzeczywistości robi Y”, to nie to powiedziałem. Mówię o zrozumieniu, co robi kod , ale nie o tym, co powinien zrobić. Załóżmy, że podejrzewasz błąd „jeden po drugim”. Skąd wiesz, że błędu typu „jeden po drugim” nie ma w konsumującym się kodzie, a nie w tym kodzie? Komentarze wyjaśniają cel kodu, co ogromnie pomaga w śledzeniu błędów.
Danny Tuppeny
Z drugiej strony komentarze mogą tylko powiedzieć, co powinien zrobić kod w chwili pisania komentarzy. Sam kod może powiedzieć ci, co powinien teraz zrobić . Komentarze się nie kompilują. Nie możesz testować komentarzy. Mogą, ale nie muszą być poprawne.
Anthony Pegram
3

Komentarze, które są wstawiane, ponieważ ktoś uważa, że ​​posiadanie 700 linii w jednej metodzie jest w porządku, to zapach.

Komentarze, które tam są, ponieważ wiesz, że jeśli nie dodasz komentarza, ktoś popełni ten sam błąd po raz kolejny to zapach.

Komentarze zostały wstawione, ponieważ niektóre narzędzia do analizy kodu wymagają, aby był to także zapach.

Ludzie, którzy nigdy nie dodadzą komentarza ani nie piszą żadnej pomocy dla innych programistów, również pachną. Dziwi mnie, jak wiele osób nie zapisuje rzeczy, ale potem odwraca się i potwierdzam, że nie pamiętają, co zrobili 3 miesiące temu. Nie lubię pisać dokumentów, ale lubię ciągle powtarzać ludziom to samo.

MIA
źródło
3

Odpowiem na własne pytanie. Czy możesz znaleźć błąd w nieskomentowanym kodzie poniżej?

tl; dr: Następna osoba, która utrzyma twój kod, może nie być tak podobna do boga jak ty.

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  push ax
  add bx, 1
  add cx, 1
  jmp strreverse_push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55
Mrówka
źródło
Ale w dzisiejszych czasach nie używasz języka wysokiego poziomu?
Ian
2
@Ian: Program jest programem ładującym IBM-PC. Nie możesz napisać go w żadnym innym miejscu niż montaż, ponieważ potrzebujesz całkowitej kontroli nad tym, gdzie dokładnie program znajduje się w pamięci RAM, gdzie pojawia się ostatni skrót, a także niektóre przerwania sprzętowe. Poważnie, zdobądź kopię NASM. Złóż go, napisz do sektora rozruchowego dyskietki lub pamięci USB i uruchom. Chociaż prawdopodobnie okaże się, że nie działa zgodnie z oczekiwaniami z powodu błędu. Teraz znajdź błąd ... Bez względu na to, jestem pewien, że za 20 lat ludzie będą pytać o to samo, co niekomentowana Java.
Ant
Z pewnością kod mógłby być napisany w C lub C ++, a plik binarny skompilowany z kodu obiektowego C i jakiegoś zewnętrznego narzędzia.
kevin cline
Niestety nie. Zajrzyj na tę stronę w CodeProject: codeproject.com/KB/tips/boot-loader.aspx - „języki wysokiego poziomu nie mają niezbędnych instrukcji”. Mało tego, ale masz tylko 512 bajtów do zabawy w bootloaderze. Czasami musisz po prostu dostać się bezpośrednio do sprzętu.
Ant
1
Podczas kodowania asemblacji robiłbym to, co wszyscy inni - komentował każdą linię z tym, co robi. Linia, o której mowa, miałaby komentarz „sprawdź, czy litera ma wartość 0”, ponieważ kod używa ciągów zakończonych cyframi typu 0. Po umieszczeniu tego komentarza łatwo jest zauważyć, że kod wykonuje polecenie cmp z wartością 1, co oznacza, że ​​albo utknie w nieskończonej pętli, albo drukuje śmieci, aż trafi losowo na 1 w pamięci RAM. Mogłem również dodać komentarz o tym, że łańcuchy były zakończone na 0, co nie wynika z kodu. Czy istnieje coś takiego jak zautomatyzowane testowanie jednostkowe kodowania zestawu?
Ant
2

Musisz zachować równowagę między kodem a komentarzami ... Zwykle staram się dodawać komentarze, które wznawiają blok kodu. Nie dlatego, że nie będę w stanie zrozumieć kodu (no cóż, to też), ale dlatego, że mogę szybciej czytać własny kod i znajdować określone sekcje, w których dzieją się ważne rzeczy.

W każdym razie moje własne kryteria to „w razie wątpliwości komentuj”. Wolę mieć nadmiarową linię niż całkowicie tajemniczą linię, której nie będę w stanie zrozumieć. Zawsze mogę po pewnym czasie usunąć komentarze do recenzji kodu (i zwykle tak robię)

Ponadto komentarze są bardzo pomocne, dodając „zastrzeżenia”, takie jak „Uważaj! Jeśli formatem wejściowym nie jest ASCII, ten kod będzie musiał się zmienić!”

Khelben
źródło
Czy możesz wyjaśnić, co rozumiesz przez „komentarze wznawiające blok kodu”?
Mark C
2

Czytając to, przypominam sobie coś, co po raz pierwszy przeczytałem (z dłuższej listy, zachowanej przez robienie kserokopii) kilka dekad wstecz:

Prawdziwi programiści nie piszą komentarzy - jeśli trudno było napisać, powinno być trudno je przeczytać

Raczej starszy zapach.

Murph
źródło
2

Myślę, że komentowanie kodu ma bardzo słaby początek. Nie wiem o tych dniach, ale kiedy po raz pierwszy uczyłem się programowania w szkole, dostałem zadania w rodzaju „Napisz program, który drukuje liczby od jeden do dziesięciu w osobnych wierszach. Pamiętaj o skomentowaniu kodu”. Zostaniesz oznaczony, jeśli nie dodasz komentarzy, ponieważ komentowanie kodu to DOBRA RZECZ.

Ale co można powiedzieć o tak trywialnym procesie? W rezultacie piszesz klasykę

i++; // add one to the "i" counter.

tylko po to, aby uzyskać przyzwoitą ocenę i, jeśli masz jakieś złe, natychmiast formułować bardzo niską opinię o komentarzach do kodu.

Komentowanie kodu nie jest DOBREJ RZECZY. TO CZASEM NIEZBĘDNE RZECZY, a Thomas Owens w pierwszej odpowiedzi stanowi doskonałe wyjaśnienie sytuacji, w których jest to konieczne. Jednak sytuacje te rzadko pojawiają się w zadaniach domowych.

Pod wieloma względami dodanie komentarza należy uznać za ostateczny wybór, gdy tego, co należy powiedzieć, nie można jasno powiedzieć w aktywnych częściach języka programowania. Chociaż nazewnictwo obiektów może być nieaktualne, różne mechanizmy braku sprzężenia zwrotnego od ludzi i komputerów ułatwiają zapominanie o utrzymywaniu komentarzy, w wyniku czego komentarze stają się nieaktualne znacznie szybciej niż aktywny kod. Z tego powodu, tam gdzie możliwy jest wybór, zawsze należy preferować zmianę kodu, aby był bardziej przejrzysty, niż dodawanie do niejasnego kodu komentarzy.

Alohci
źródło
+1 za wskazanie, że złe nawyki związane z komentowaniem zaczynają się od zajęć z wczesnego programowania. -1 za stwierdzenie, że komentarze są tylko ostatecznością.
AShelly,
1

Oczywiście komentarze to zapach kodu ...

każdy programista wie, że w końcu wszyscy oszaleliśmy powodu pracy, debugowania lub zwykłego szaleństwa, na które wpadamy.

"Zrób to!" mówi kierownik projektu.

Odpowiadasz: „Tego nie da się zrobić”.

Mówią: „W takim razie znajdziemy kogoś innego”.

Mówicie: „OK, cóż, może da się to zrobić”.

A następnie spędzić następną liczbę dni X .. tygodni .. miesięcy .. próbując to rozgryźć. W trakcie tego procesu będziesz próbować i nie powiedzie się, i spróbujesz i nie powiedzie się. Wszyscy to robimy.Prawdziwa odpowiedź jest taka, że ​​istnieją dwa typy programistów: ci, którzy komentują i ci, którzy nie komentują.

1) Ci, którzy to robią, albo ułatwiają własną pracę, dokumentując na przyszłość, komentując nieudane procedury, które nie działały (zapach nie usuwa ich po znalezieniu tej, która działa) lub łamią kod z komentarzem formatowanie, które, miejmy nadzieję , nieco ułatwi czytanie lub zrozumienie. Poważnie, nie mogę ich winić. Ale w końcu pękają, a potem masz to: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) Ci, którzy nie udają superbohatera lub żyją w jaskini . Po prostu lekkomyślnie lekceważą innych i siebie, i mogą mniej przejmować się kodem lub jego znaczeniem na później.

Nie zrozumcie mnie źle… zmienne i funkcje samodokumentujące mogą tego całkowicie uniknąć… i wierzcie mi, że nigdy nie można zrobić wystarczająco dużo czyszczenia kodu. Ale prosta prawda jest taka, że ​​dopóki przechowujesz kopie zapasowe, możesz ZAWSZE usuwać komentarze.

Talvi Watia
źródło
1
W odpowiedzi na 1. Prawdziwy zapach w komentowanych procedurach nie usuwa ich od razu, gdy zdecydujesz, że są ślepymi zaułkami i chcesz spróbować czegoś innego --- to dlatego, że powinny być dostępne w kontroli wersji, jeśli zdecydujesz się na nie ponownie .
Sharpie
1

Twierdziłbym, że niestosowanie niektórych komentarzy w kodzie to zapach kodu. Chociaż zgadzam się, że kod powinien samokontraktować się w jak największym stopniu, osiągnąłeś punkt, w którym zobaczysz kod, który nie ma sensu bez względu na to, jak dobrze kod jest napisany. W aplikacjach biznesowych widziałem kod, w którym komentarze są obowiązkowe, ponieważ:

  1. Musisz zrobić coś indywidualnie dla każdego przypadku i nie ma na to dobrej logiki.
  2. Kod najprawdopodobniej zmieni się za rok lub dwa, gdy zmieni się prawo, a Ty chcesz go szybko znaleźć.
  3. Ktoś edytował kod w przeszłości, ponieważ nie rozumiał, co robi kod.

Przewodniki w stylu firmowym mogą również zalecić zrobienie czegoś w określony sposób - jeśli mówią, że powinieneś mieć komentarze określające, co robią bloki kodu w funkcji, dołącz komentarze.

rjzii
źródło
1

Istnieje duża fundamentalna różnica między komentarzami a kodem: komentarze są sposobem, w jaki ludzie mogą przekazywać pomysły innym ludziom, podczas gdy kod jest przeznaczony głównie dla komputera. W „kodzie” jest wiele aspektów, które dotyczą tylko ludzi, na przykład nazywanie nazw i wcięcia. Ale komentarze są napisane wyłącznie dla ludzi, przez ludzi.

Dlatego pisanie komentarzy jest tak samo trudne, jak każda pisemna komunikacja ludzka! Autor powinien mieć jasne pojęcie o tym, kim jest publiczność i jakiego rodzaju tekstu będzie potrzebował. Skąd możesz wiedzieć, kto przeczyta twoje komentarze za dziesięć, dwadzieścia lat? Co jeśli osoba pochodzi z zupełnie innej kultury? Itd. Mam nadzieję, że wszyscy to rozumieją.

Nawet w małej homogenicznej kulturze, w której żyję, tak trudno jest przekazywać pomysły innym ludziom. Komunikacja ludzka zwykle kończy się niepowodzeniem, z wyjątkiem przypadku.

użytkownik15127
źródło
0

Muszę się zgodzić z twoim współpracownikiem. Zawsze mówię, że jeśli skomentuję mój kod, oznacza to, że martwię się, że nie będę w stanie wymyślić własnego kodu w przyszłości. To zły znak.

Jedynym innym powodem, dla którego umieszczam komentarze w kodzie, jest wywołanie czegoś, co wydaje się nie mieć sensu.

Te komentarze zwykle mają formę:

//xxx what the heck is this doing??

lub

// removed in version 2.0, but back for 2.1, now I'm taking out again
Rozpoznać
źródło
1
Ewentualnie komentarz może odzwierciedlać fakt, że kod odnosi się do złożonego algorytmu, w którym kod z natury staje się nieoczywisty lub dlatego, że kod robi coś dziwnego z powodu czynników niezależnych od ciebie (np. Interakcji z usługą zewnętrzną).
Murph
Bardzo prawdziwe. Istnieją powody, dla których dobry kod może nie być oczywisty. Przez większość czasu kłopotliwy kod jest kłopotliwy, ponieważ jest napisany w zaciemniony sposób.
Ken
Wygląda na to, że nie napisałeś kodu dla wbudowanych procesorów, w których masz tylko 32k do odtworzenia, a rzeczy są dla ciebie nieznane. Komentarze ratują życie.
szybko_nie
0

Komentarze do kodu podające, w stosownych przypadkach, jednostki argumentów i zwrotów funkcji, pola struktury, a nawet zmienne lokalne mogą być bardzo przydatne. Pamiętaj o Mars Orbiter!

dmuir
źródło
Znacznie lepiej jest wbudować jednostki w nazwy zmiennych, aby biedny programista nie musiał ich pamiętać. Zamiast „podwójnej długości // w metrach” powiedz „podwójnej długości_m”. Najlepsze ze wszystkiego jest użycie mocniejszego języka, abyś mógł po prostu powiedzieć Długość l; Siła f; Moment obrotowy t = l * f; print (t.in (Torque.newtonMeter));
kevin cline
0

Oto moja ogólna zasada:

  • Napisz kod i zapisz krótkie streszczenie kodu w osobnym dokumencie.
  • Pozostaw kod w spokoju na kilka dni, aby popracować nad czymś innym.
  • Wróć do kodu. Jeśli nie możesz od razu zrozumieć, co ma zrobić, dodaj podsumowanie do pliku źródłowego.
Maks
źródło
0

Nie, komentarze nie są zapachem kodu, są tylko narzędziem, które można wykorzystać.

Przykłady dobrych komentarzy:

// Myślę, że to jest w cm. Konieczne dalsze dochodzenie!

// To sprytny sposób wykonywania X

// Lista nie może być tutaj pusta

Andres F.
źródło
Trzeci to zły komentarz IMO. Dlaczego nie Assert(list.IsEmpty)?
CodesInChaos
@CodeInChaos IMO Assert(!list.isEmpty())nie jest dokładnie umową jak w trzecim komentarzu, ale po prostu zachowaniem (tj. „Wyrzuć IllegalArgumentException, jeśli argument jest pusty”), który musi być testowany jednostkowo, jak każda inna logika programu. Zwróć uwagę na subtelną różnicę w komentarzu, która określa, kiedy można zastosować metodę, ale nie określa zachowania, jeśli warunek wstępny nie jest spełniony. Jeszcze lepszym rozwiązaniem byłoby egzekwowanie umów na czas kompilacji. Ale to przekracza zakres mojej odpowiedzi;)
Andres F.
Nie powinieneś być w stanie wykonywać Asserts, ponieważ opisują rzeczy, które nigdy nie powinny się zdarzyć, nawet jeśli publiczny interfejs API otrzyma nieprawidłowe argumenty.
CodesInChaos
@CodeInChaos Wycofuję swoją opinię. Oto, co Sunacle ma do powiedzenia na temat twierdzeń . Wygląda na to, że miałeś rację. Cóż, uczysz się czegoś każdego dnia!
Andres F.,