Czy nieaktualne komentarze to miejski mit?

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?

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.