Czy nieaktualne komentarze to miejski mit?

38

Ciągle widzę ludzi twierdzących, że „komentarze stają się nieaktualne”. Chodzi o to, myślę, że widziałem może dwa lub trzy nieaktualne komentarze przez całą moją karierę. Nieaktualne informacje w osobnych dokumentach zdarzają się cały czas, ale z mojego doświadczenia wynika, że ​​nieaktualne komentarze w samym kodzie są niezwykle rzadkie.

Czy mam szczęście, z kim pracuję? Czy niektóre branże są bardziej podatne na ten problem niż inne? Czy masz konkretne przykłady ostatnich nieaktualnych komentarzy, które widziałeś? A może przestarzałe komentarze są bardziej problemem teoretycznym niż faktycznym?

Karl Bielefeldt
źródło
30
Zgoda. Przestarzały kod przekształcony w komentarz, teraz to jest coś, co często widzę - i chciałbym zobaczyć mniej.
pyvi
8
Widzę większy brak komentarzy niż cokolwiek innego. W połączeniu ze słabymi konwencjami nazewnictwa jest to świetna zabawa, próbując przeczytać niektóre rzeczy, z którymi pracuję.
P.Brian.Mackey
2
Widziałem wiele nieaktualnych komentarzy, niektóre były po prostu mylącym ZŁEM. Zdecydowanie żaden mit, ale dotyczy to głównie projektów prowadzonych przez wiele osób i / lub przez długi czas, powiększonych o złożoność. Nauczyłem się jednak ufać kodowi, a nie komentarzom (prawie nigdy ich nie czytałem, jeśli przekraczają więcej niż jeden dwa wiersze).
MAR
Przez całą moją karierę pracowałem głównie ze starym, starszym kodem. Kilkanaście razy miałem poważne problemy związane z nieaktualnymi komentarzami w dziwnym 30-letnim kodzie Fortan77, ale było to prawie zero procent kodu, w którym komentarze były odpowiednie. Zgadzam się więc, skala problemu musiała być przesadzona.
SK-logic
Tylko moje szczęście, widziałem sporo w ciągu roku, odkąd to opublikowałem. Wydaje mi się, że podświadomie nauczyłem się im nie ufać, a potem poprawiać je i iść naprzód, nie zastanawiając się nad tym, by zapamiętać to w pamięci długoterminowej.
Karl Bielefeldt

Odpowiedzi:

33

Stale

Naprawdę nie mogę uwierzyć, że tylko ja pływam w przestarzałych i mylących komentarzach. W przypadkowym przypadku pomaga to w zrozumieniu:

Prawdopodobnie zależy to przede wszystkim od wieku kodu. Następnym czynnikiem byłby obrót personelu.

Wykonuję równe części prac badawczo-rozwojowych i prac konserwacyjnych. R&D to nowy kod, ogólnie rzecz biorąc, który jest trochę na uboczu. Wielu moich kolegów wierzy w wiele skomentowanych wyjaśnień, próbując czegoś, dla czego nie ma jeszcze biblioteki. Ponieważ stosunek komentarzy do kodu jest wyższy niż zwykle, istnieje więcej możliwości, aby coś zsynchronizować.

Kod konserwacji ... Jestem aktywnym opiekunem w systemie, który ma ponad 10 lat, a inny, który ma ponad 5 lat. 10-letni kod i komentarze są okropne, jak można się spodziewać. W ciągu 10 lat masz dużo rąk w bazie kodu i nikt nie ma pojęcia, jak to wszystko działa. 5-letni kod i komentarze są całkiem dobre, ponieważ obroty w zespole są dość niskie.

Pracuję prawie we wszystkich usługach, nawet nasze produkty są ściśle dostosowane do konkretnego klienta.

Konkretne przykłady:

  • Komentarze opisujące poprawę wydajności dla określonej metodologii, takie jak unikanie kopii w pamięci. Wielka sprawa, gdy najwyższej klasy maszyna w Pentium 2 z MB pamięci RAM, ale teraz nie stanowi większego problemu.

  • DO ZROBIENIA

  • Bloki wklejonego kodu wraz z komentarzami. Komentarz mógł mieć sens w pierwotnej lokalizacji, ale tutaj nie ma sensu

  • Bloki komentarzy na górze skomentowanego kodu (kto wie, ile lat tam było).

We wszystkich tych trendach po prostu nie utrzymuje się komentarzy i kodu na tym samym poziomie co oprogramowanie. IDE i podstawowe nawyki programistów nie pomagają w tym, moje oko zostało wyszkolone, aby je wyprzedzać. Myślę, że komentarz przestarzały jest stosunkowo tani, aby uniknąć go w zielonych projektach i aktywnych projektach. Jeśli możesz utrzymać wysoki współczynnik kod / komentarz, nie jest wielkim problemem, aby być na bieżąco. Trochę trudniej jest usprawiedliwić polowanie na te rzeczy, gdy masz budżet x godzin na naprawę błędu w systemie produkcyjnym.

Steve Jackson
źródło
Mówiąc w zasadzie, po prostu całkowicie ignorujesz komentarze, ponieważ jest to już zbyt duży bałagan, tylko pogarszając twoją sytuację. Nic dziwnego.
Steven Jeuris,
5
@Steven - Ja osobiście, nie. Wierzę w stopniową poprawę. Widziałem, jak warczenie całkowicie nieczytelnego kodu zmienia się w coś całkiem przyzwoitego przy wystarczającym stopniowym wysiłku. Ale ignorowanie jest z pewnością normą z mojego doświadczenia. Jest to bardzo zrozumiałe, gdy natrafisz na kilka przeplatających się 10000 klas linii z tygodniowymi problemami do skatalogowania, że ​​nieaktualne komentarze zwykle spadają na dół listy priorytetów.
Steve Jackson
1
@ Steve: W twojej sytuacji po prostu stworzę skrypt, który usuwa wtedy wszystkie komentarze i zacznę komentowanie od zera w razie potrzeby. :)
Steven Jeuris
1
główną bazą kodu, w której pracowałem, było co najmniej pół komentarza i kod rzadko komentowany. Nieaktualne komentarze były faktem, poprawne komentarze były niezwykle rzadkie i nawet nie zacznę komentować dokumentacji !!! widok ... Po tej pracy dowiedziałem się, że mniej jest dobre, jeśli kod wymaga komentarza, to prawdopodobnie potrzebuje Refactor Żeby było bardziej oczywiste ...
Newtopian
4
Widziałem kilka okropnych przykładów Blocks of copy-pasted code including comments. Comment may have made sense in its original location, but hardly makes sense here. Komentarze na poziomie klasy mówiące na przykład o innej klasie.
Peter Taylor,
18

„komentarze stają się nieaktualne”.

Widziałem to wystarczająco często, aby wiedzieć, że może to stanowić problem.

Chodzi o to, myślę, że widziałem może dwa lub trzy nieaktualne komentarze przez całą moją karierę.

Uważam, że praca w środowisku, w którym każdy dba o komentarze i je utrzymuje, powinna być całkowicie możliwa. To tylko niewielki dodatkowy wysiłek, aby spojrzeć na komentarze w pobliżu edytowanego kodu i zaktualizować je w razie potrzeby. Jeśli komentarze są tak daleko, że nie zauważysz ich od razu, i tak były to złe komentarze i nie powinny były zostać dodane (a przynajmniej ich nie ma).

Ponadto zwykle wraz ze stwierdzeniem, że komentarze stają się nieaktualne, następuje po stwierdzeniu, że zmniejsza to czytelność i dezorientuje ludzi. Tego jeszcze nie doświadczyłem. Za każdym razem, gdy napotykam nieaktualny komentarz, wyraźnie widzę, co się zmieniło, i po prostu odpowiednio aktualizuję komentarz, aby reprezentował nowszy kod, choć z pewnym dodatkowym wysiłkiem.


Ostatnie badanie Roehm i in. 2012 obserwuje następujące kwestie:

21 uczestników [z 28] zgłosiło, że uzyskuje swoje główne informacje z kodu źródłowego i umieszcza komentarze, podczas gdy tylko czterech twierdziło, że dokumentacja jest ich głównym źródłem informacji.

Jest to zgodne z twoim podejrzeniem, że komentarze w samym kodzie ogólnie są nadal uważane za bardzo przydatne. Wskazuje to na wyraźną granicę między nieaktualną dokumentacją a nieaktualnymi komentarzami .

Roehm, T., Tiarks, R., Koschke, R., i Maalej, W. (2012, June). Jak profesjonalni programiści rozumieją oprogramowanie ?. W materiałach z międzynarodowej konferencji na temat inżynierii oprogramowania z 2012 r. (Str. 255–265). IEEE Press.

Steven Jeuris
źródło
Gdy stałem się lepszy, stwierdziłem, że potrzebuję mniej komentarzy, aby zrozumieć, co robi kod w typowym kodzie plug-and-chug.
Paul Nathan
3
@Paul Nathan, komentarze nigdy nie powinny opisywać tego, co robi kod - kod lepiej to opisuje. Komentarze mają na celu wyjaśnienie, dlaczego kod robi to, co robi.
SK-logic
2
@ SK-logic: Chociaż rozumiem argument, który uważam za zbyt szeroki. Komentarze funkcji (lub akapitu / bloku kodu) mogą wyjaśnić znacznie więcej (i szybciej), co robi funkcja niż jej nazwa. Jest to szczególnie potrzebne w przypadku funkcji publicznych. Czytanie kodu jest tak proste, jak czytanie dwuliniowego objaśnienia kodu 10-liniowego jest jeszcze szybsze. Wyobraź sobie pracę z ulubionym interfejsem API, który nie ma żadnej dokumentacji „co” . Będziesz o wiele mniej pewny co do jego funkcjonalności.
Steven Jeuris,
tak, nie załączyłem dokumentacji (np. Javadoc) - jest ona zbyt strukturalna, aby nazywać ją „ komentarzem ”.
SK-logic
17

Nieaktualne komentarze to zapach pracy. To tak, jakby mieć przestarzałe lub zaniedbane testy jednostkowe - pokazuje, że dobre procesy, które kiedyś były aktywne w sklepie, przeradzają się w kodowanie kowbojskie. Zniszczyła się właściwa „kultura inżynierii” polegająca na tym, że nie spieszy się z robieniem rzeczy. Projekt / firma prawdopodobnie popadnie w długi techniczne.

Krótko mówiąc, tak, miałeś szczęście. Jeśli do tej pory miałeś w swojej karierze szereg dobrze zarządzanych sklepów, całkiem możliwe, że nie zobaczysz tak wiele. Ale w bardziej typowych, gorzej zarządzanych sklepach dzieje się to równolegle z resztą chaosu.

Stoły Bobby'ego
źródło
„Nieaktualne komentarze to zapach pracy”. Bardzo dobrze powiedziane! Podobnie samokodujący się kod tylko bez komentarzy nie jest rozwiązaniem, ale leniwym „hackiem”.
Steven Jeuris,
10

Komentarze są jak testy, są bardzo dobre, gdy są aktualne, ale mogą utrudnić zrozumienie kodu, jeśli go nie ma.

Jeśli nigdy nie widziałeś nieaktualnych komentarzy, miałeś dużo szczęścia.

Większość baz kodu, z którymi pracowałem, była pełna nieaktualnych komentarzy i zwykle całkowicie ignoruję komentarze, ponieważ zwykle są źródłem pomieszania, a nie pomocy.

Kim.Net
źródło
Czy mogę zapytać, w jakich branżach pracowałeś? Zastanawiam się, czy u niektórych jest to bardziej powszechne.
Karl Bielefeldt,
Pracowałem w 3 różnych krajach w Europie, głównie jako konsultant dla dużej i małej firmy. Ostatnio w domu deweloperskim SaaS.
Kim.Net
patrz także: „Komentarze to zapach kodu”
komik
10

Nieaktualne komentarze często pojawiają się w JavaDoc:

  • Lista argumentów, które już nie istnieją
  • Nie wyjaśniam wszystkich argumentów (brakujące zostały prawdopodobnie dodane później)
  • Podobne rzeczy dla wyjątków itp.

Ponadto czasami komentarze stwierdzają takie rzeczy, jak „zrób to tutaj, aby uzyskać wydajność”, gdy większość kwestii dotyczących wydajności staje się przestarzała nawet szybciej niż sam kod.

Deckard
źródło
3
(Nie krytyka - po prostu przedstawienie rozwiązania) Ostrzeżenia IDE mogą znacznie pomóc w zapobieganiu temu. Jeśli potrzebne są bardziej drastyczne środki, zakończ kompilację ostrzeżenia / błędu kompilacji javadoc.
Michael K
1
To może wyjaśniać, dlaczego nie widziałem zbyt wielu. Nigdy nie pracowałem w miejscu, które używa komentarzy w stylu JavaDoc.
Karl Bielefeldt,
4
@Michael, ostrzeżenia IDE są pomocne w łagodnych przypadkach. Nasza starsza baza kodów generuje ponad 20 000 ostrzeżeń Checkstyle, to znacznie ponad limit, w którym przestajesz zwracać uwagę: - ((IDE, gdy źle użyte, mogą znacznie przyczynić się do nieszczęścia Javadoc. Większość bzdur Javadoc w naszej bazie kodu była oczywiście generowana automatycznie.
Péter Török,
4

Od czasu do czasu zajmuję się przestarzałymi komentarzami. Z pewnością nie jest to mit miejski. Ludzie wspominają o tym na listach najgorszych praktyk, nie dlatego, że często cię uderzają, ale dlatego, że kiedy tak się dzieje, zwykle kosztuje to dużo czasu i wysiłku.

W naszej bazie kodu większość nieaktualnych komentarzy jest spowodowanych użyciem (anty) wzorca opisującego zachowanie metody w pobliżu jej wywołania, a nie w pobliżu deklaracji metody. Dzieje się tak, gdy ktoś wyodrębnia długi fragment kodu do metody, która jest wywoływana tylko raz, a następnie komentuje wywołanie metody. W efekcie powstaje coś takiego:

featureList = GetFeatures();

// Sorting features and deleting empty ones from the list...
ProcessFeatures(featureList);

Metoda została zadeklarowana gdzieś poniżej bez komentarzy. Przez lata ludzie borykają się z tymi metodami, zajmując się zmianami specyfikacji i naprawianiem błędów, a ostatecznie uzyskuje się metodę, która nie sortuje listy i zgłasza wyjątek, gdy znajdzie pustą funkcję. Tak więc powyższy komentarz jest przestarzały, co w końcu będzie cię kosztować trochę czasu w debuggerze. Zdarza się to w niektórych bazach kodów.

Dyppl
źródło
3

Zadaj sobie to pytanie. Czy kiedykolwiek zmieniłeś wiersz kodu i nie zmieniłeś powiązanych komentarzy ani nie dodałeś nowych?

Pracowałem z wieloma starszymi kodami, a komentarze czasami nie są nawet odpowiednie.

Bill Leeper
źródło
2

W większości moje doświadczenie pasuje do twojego, ale natknąłem się na jeden przypadek, w którym było to prawdą w całej bazie kodu. Była to aplikacja napisana wiele lat wcześniej przez sklep konsultingowy, który nie był już „na dobrych warunkach” z klientem.

Firma wykonała wyjątkową robotę komentując kod, ale programiści, którzy utrzymywali go od czasu pierwotnego przekazania, byli częścią sposobu myślenia „jedyna zmiana, co absolutnie trzeba zmienić”, która sama w sobie nie jest zła. Niestety zachowali to samo podejście do komentarzy, co z czasem doprowadziło do dość dużego rozdźwięku między komentarzami a kodem.

Dave Wise
źródło
2

Nie widzę zbyt wielu komentarzy opisowych, które stają się nieaktualne, ale widzę wiele komentarzy TODO, które były tam od lat. Chciałbym, żeby były jak kapsuły czasu i powiedział coś takiego:

//TODO: In 15 years AND NO SOONER... actually implement this method.
Morgan Herlocker
źródło
1
Problemem w tym przypadku jest prawdopodobnie niewłaściwe użycie TODO. Uważam, że TODO powinny być używane tylko wtedy, gdy kod jest rzeczywiście funkcjonalny, ale ulepszenia mogą być wprowadzone później, więc tego TODO: implementrodzaju komentarze nie powinny istnieć, a fakt, że nikt tak naprawdę nie wrócił, nie ma większego znaczenia. Niestety, niewiele osób przestrzega tej zasady i całkowicie się zgadzam, że chciałbym zobaczyć komentarz taki jak ty w jakimś kodzie produkcyjnym. To sprawi, że mój dzień.
pwny,
1
W języku C # używam NotImplementedException do tych celów.
Steven Jeuris
2
@pwny, używam TODO tylko do rzeczy, które planuję napisać przed odprawą, aby upewnić się, że to obejmuję. Moim zdaniem cokolwiek długoterminowego należy do narzędzia do śledzenia błędów.
Karl Bielefeldt,
@Karl Bielefeldt To też ma sens.
pwny,
2

Ostatnie 3 projekty, nad którymi pracowałem, spędziłem kilka dni na każdym usuwaniu nieaktualnych, mylących i po prostu bezużytecznych komentarzy z bazy kodu. Tam, gdzie to możliwe i konieczne, zastępuję je bardziej odpowiednimi komentarzami, ale najczęściej jest to tylko kwestia usunięcia komentarza i przejścia dalej.

Zrobiłem to samo na prawie każdej bazie kodu, którą kiedykolwiek przejęłem od innych, zwykle po tym, jak przez jakiś czas był nieobsługiwany, a pierwotni właściciele już dawno odeszli i / lub nie chcieli lub nie byli w stanie dokonać właściwego przekazania.

jwenting
źródło
1

Może to być spadek wykorzystania komentarzy. Jaka część kodu jest kwalifikowalna? Po pierwsze, ktoś musi dołączyć komentarze, aby były nieaktualne. Po drugie, skomentowany kod musi zostać zmieniony. Nie jestem pewien, czy kwalifikuje się wysoki procent kodu.

Musisz polegać tylko na jednym złym komentarzu, aby zrujnować dużą część aplikacji i zmarnować dużo czasu.

JeffO
źródło
0

W organizacji, która produkuje dużo kodu, trudno jest zsynchronizować komentarze. Najlepszym sposobem na zrozumienie tego, co się dzieje, jest użycie oprogramowania, które rysuje schemat blokowy modułu, nad którym pracujesz. To jedyny sposób, aby dowiedzieć się, co robi oprogramowanie.

Gaurav Sehgal
źródło