Czy komentarze są passe?

Niby powinno się pisać samodokumentujący się kod, poprawnie nazywać metody/zmienne i nie żałować tworzenia dodatkowych.
Dopuszcza się jeszcze Javadoc-i - ale one opisują jak użyć danej metody i parametry wejściowe.
W mojej pracy komentarzy się nie stosuje - w sporym projekcie, w którym pracowałem, nie było ani jednego komentarza, który nie był jednocześnie Javadociem.
Jak jest u was, czy stosujecie komentarze w ogóle? Czy uważacie, że używanie ich jest złe i od razu świadczy że jakiś kod został źle napisany? Bo ja jakoś w niektórych miejscach (np domenowych algorytmach) czuje że przydałby się jakiś komentarz, mimo to nie stosuje ich, bo nie przechodzą review.

Akurat algorytmy to miejsca, w których komentarze są jak najbardziej wskazane.

Albo jak robisz coś WTFowego, np. hak na obejście buga w przeglądarce, jak to się czasem w webdevie robi. Ew. jak robisz coś, co nie musi być do końca jasne i chcesz zasygnalizować komuś, co poeta miał na myśli (np. w algorytmach). Albo zwrócić uwagę na jakiś element kodu, o którym wiesz, że może być błędogenny. Albo komentarze TODO, które są wskazaniem dla innych członków zespołu (i dla nas samych), że potem dany kod jest tymczasowy/niedorobiony i później trzeba będzie to zmienić...

Generalnie komentarze to bardziej jak tabliczki "objazd", "świeżo malowane" albo "przystanek czasowo skasowany". Jest to czasem potrzebne, ale to nie jest coś, co ma wartość samą w sobie i co należy gloryfikować.

Generalnie komentarze są passe bo jeśli musisz takowy napisać to znaczy że należałoby jednak zmienic nazwy/wydzielic metodę etc. Ale są pewne rzeczy których NIE DA sie udokumentować kodem. W przypadku algorytmów są to na przykład motywacje (czemu ten a nie inny algorytm), albo teoretyczny opis "czemu to działa". Tak samo jeśli wrzucamy w kod jakiś "hack" na konkretne issue to dobrym pomysłem jest napisać o co chodziło albo dać referencje do issue trackera (i oczywiście napisać unit test który ten przypadek sprawdza aby wykluczyć regresje).

Gdy przy projekcie pracuje 20 osób, gdy łączenie do bazy jest wykonywane przy pomocy i warstwy połączniewej i bezpołączeniowej i EF, gdy baza ma killaset tabel, gdy korzysta się z dwóch wersji kompilatora. Każda wskazówka jest na wagę złota :)
Komemtarze są darem dla robaczków jak ja, którzy pracują z kodem. Komentuję każdą rzecz która nie jest mocno standardowa, nawet jeśli reszta tego nie robi. Jak trafię na ten kod za rok to sam sobie podziękuję :)

Guzik prawda. Bo ten kod za rok, dwa, pięć będzie robił co innego, innymi metodami a komentarz poznawanie bez zmian. I będziesz klął na to że kod nijak się ma do komentarzy. Poza tym jeśli musisz napisać komentarz żeby ktoś mógł zrozumieć dany kod (w sensie jak działa i co robi) to znaczy że kod który napisałeś jest słabej jakości.

Kolego, nie ja projektowałem system, i nie ja wytyczałem jego założenia. Ja jedynie muszę wprowadzić modyfikacje pożądane przez klienta - konkretne modyfikacje - i co ważne, w konkretnym czasie, bo każda godzina jest rozliczana - płaci klient. Trzeba wgrać na produkcję, ma działać. A na wspomienie o unit testach kierownik robi się czerwony.
Ciężko odwoływać się w takiej sytuacji do dobrych praktyk, gdy w jednej metodzie masz pomieszany kod linqu i czystego sql'a oraz operacje na listach :D A ja nie jestem od tego by to porządkować bo nie mam na to czasu.
Tak jak pisałem, jeśli coś nie jest standardowe, to warto komentować, szczególnie jeśli musisz rzeźbić w gó...e.

Z tego co piszesz, to pracujesz w JanuszSofcie. Współczuję. Z drugiej strony gdybyście zamiast hakować, zaczęli refaktoryzować malutkimi kawałkami kod, to później by się okazało, że kolejne taski szły by szybciej. Żyjecie na wiecznym kredycie technologicznym i żeby go spłacać, zaciągacie kolejne kredyty.

Nie moja sprawa, na szczęscie.

@LukeJL Nie koniecznie JanuszSoft. Jeśli pracujesz w miedzynarodowej korporacji, w projekcie przez nią zakupionym który ma swoje początki w latach 90, w dodatku był pisany bez pomyślunku o odpowiedniej architekturze, to to też jest rzeźniebie w g... Jedynie podejscia do pisania UnitTestów nie rozumiem, bo narzut jest niewielki a potem ratuje przed większymi fackupami.

@misiakufal sensowna firma wie że jeśli ma ten produkt utrzymywać/rozwijać przez następne kilka lat to TRZEBA go doprowadzić do jako-takiego stanu od razu, bo później będzie za późno.
@kreis84 to uciekaj z tej firmy ;) poza tym ciekawi mnie jak rozlicza was klient z regresji w takim razie skoro nie piszecie testów. Bo nie wierze że nie ma regresji.

zazwyczaj komentarze mi pomagały i myślę, że są przydatne (stosowane z rozsądkiem). świat nie jest idealny i kod tak samo.

Shalom napisał(a):

poza tym ciekawi mnie jak rozlicza was klient z regresji w takim razie skoro nie piszecie testów. Bo nie wierze że nie ma regresji.

I masz rację. Ale ja nie być manager, ja tylko stukać w te krzaczki na klawiaturze. Więc nie mam zamiaru przejmować się tym że klient płaci podwójnie, przez to że kod jest kiepskiej jakości.
Być może przyjdzie taki piękny dzień, gdy trafię do firmy, gdzie programowanie będzie oznaczało programowanie. A nie lawirowanie między dziwnymi konstrukcjami, od patrzenia na które mózg mi się lasuje.
Taka ciekawostka: wprowadzając nowy produkt wykorzystują już EF, jest pięknie i cudownie, słonko świeci ale... cała logika biznesowa jest zaszyta w bazie, cała! I słonko zaszło.

Moim zdaniem komentarze są bardzo przydatne. Gadanie o słabej jakości kodu można włożyć między bajki, jeżeli nad projektem pracuje 30 osób to nie sposób utrzymać tam idealnego porządku, zawsze znajdzie się jakieś niejasne miejsce i nie wiadomo dlaczego jest tak a nie inaczej. Wtedy komentarz jest na wagę złota. Ja też naczytałem się książek że komentarze są beee ale teoria sobie a życie sobie.

jeżeli nad projektem pracuje 30 osób to nie sposób utrzymać tam idealnego porządku

Panie Januszu, od tego są:

• code review (!)
• sonar
• testy jednostkowe

Jeśli wszystkie 3 w projekcie są i są używane to jedyne niejasności mogą być w kontekście "dlaczego ten fragment jest napisany akurat tak" a takie niejasności powinna wyjaśniać dokumentacja API (np. javadoc dla danej klasy czy metody).

Komentarze powinny byc (i to nie zawsze) przy

• hackach
• trudnych algorytmach (np co to za algorytm)
• gdy sie robi z 1500 funkcji mniejsze funkcje i najpierw chce sie ogarnac co ta funkcja w ogole robi i sobie podzielic kod (kiedys tam robilem, teraz juz nie ;))

Nie trzeba Unit testow zeby komentarze byly zdebne, ale nie chce robic offtopa wiec nie bede tego rozwijal ;)

a jak pracuje przy kodzie nawet 100 osob to to co pisal @shalom +

• Code styleguide

i nie ma problemu

Wszystko ładnie pięknie, ale nie zawsze ma się wpływ na kształt projektu, czasem o code review czy testach jednostkowych można tylko pomarzyć.
Wtedy przynajmniej komentarze są jakimś drogowskazem w tym spaghetti code.

Czytałem kiedyś książkę o smokach i książkę w której pisali że komentarze są przydatne (symfonia?). Dziś jestem już duży i wiem że to tylko bajki.

Trochę już programuję i w życiu nie widziałem przydatnego komentarza. I wiem co mówię, bo zapamiętał bym tę unikatową chwilę. Wszystkie komenty zostawione w kodzie są zgnilizną, która długo będzie psuć pliki. Developerzy traktują je jak g**no, i uważają żeby przypadkiem nie dotknąć.

Komentarze które spotkałem można podzielić na 3 typy:
1)
//Ten kod robi A
Wyjaśnienie: Ten kod robi coś, ale na bank nie jest tym A

//TODO przerobić żeby wyeliminować X
Wyjaśnienie: Komentarz zostawiony przez gościa który rok temu opuścił firmę. X może nadal występować, a może został usunięty bez kasowania komentarza. Tego nie wie już nikt i nikt się nie dowie.

// String s = ....
//...
//...
 

Wyjaśnienie: Zakomentowany kod. Był użyteczny bardzo dawno temu. A może nie? Tego też nikt nie wie. W każdym razie za 10 lat można będzie go podziwiać w tym miejscu.

Jeżeli już faktycznie jest gdzieś miejsce na komentarz, to w kawałkach algorytmów które ciężko zrefaktorować. Ale prawda jest taka że to ułamek kodu aplikacji.

Co do javadoców i podobnych. Nie uważam że są one niezbędne i zawsze powinny wystąpić. Nie wiem skąd jest taki pogląd, ale dość często to słyszę. Bo skoro np. springdata potrafi zrobić zapytanie po nazwie metody, to znaczy że jej przeznaczenie jest jednoznaczne i to do tego stopnia że algorytm może je wyliczyć. Człowiek jest jeszcze bardziej domyślny i śmiało można zostawiać sporo metod bez komentarzy. Są miejsca gdzie oczywiście są potrzebne, np. gdy leci jakiś wyjątek, ale w większości przypadków są one niestety nadmiarowe.

IMHO wszystko zależy jaki to kod. Oczywiście, że dokumentacja nie do każdej metody jest potrzebna, ale w niektórych przypadkach warto to zrobić. I. e. w mojej bibliotece specjalnie dałem #![warn(missing_docs)] (dla niewtajemniczonych w Rusta i nieogarniętych, to znaczy, że w całej bibliotece ma rzucać ostrzeżeniem gdy brakuje dokumentacji). Oczywiście aktualnie jestem zarzygany ilością warningów, bo jestem leniem. Mam zamiar to zmienić jak tylko biblioteka będzie się do czegoś nadawać.

Czy komentarze w kodzie są potrzebne? Nie, o ile się nie robi czegoś dziwnego, a i to powinno być na tyle wyeksponowane, by było wiadomo co z czym się je. To jest, m. in. powód, dla którego lubię Rusta, większość dziwnego kodu jest w blokach unsafe i od razu widać co się dzieje.

A propos komentowania kodu:

jeżeli nad projektem pracuje 30 osób to nie sposób utrzymać tam idealnego porządku, zawsze znajdzie się jakieś niejasne miejsce i nie wiadomo dlaczego jest tak a nie inaczej. Wtedy komentarz jest na wagę złota. Ja też naczytałem się książek że komentarze są beee ale teoria sobie a życie sobie.

Rozumiem problem. Tyle, że tego typu komentarze zwykle nazywa się "dokumentacją" i zwykle się je daje nad funkcjami (a potem specjalny program je automatycznie parsuje i wypluwa dokumentację w postaci np. katalogu z powiązanymi plikami HTML). Mam wrażenie, że robicie "na dziko" coś, do czego już są automaty (co prawda ja nie lubię pochodnych JavaDoc, ponieważ to też zaciemnia kod, ale rozumiem, że jak jest 30 osób to jest taka potrzeba).

Można też tworzyć zwykłe pliki Readme w ramach dokumentacji, ew. prezentacje, diagramy etc. Można też stosować pair programming i ruszając moduł X usiąść z twórcą modułu X i razem zrobić daną funkcjonalność...

Komentarze "na dziko" rozsiane bez ładu i składu pachną mocną prowizorką i wątpię, żeby były lepszymi wskazówkami niż wyżej napisane przeze mnie przemyślane działania.

Jest jeszcze IMO jedna sytuacja. Nie wiem na ile pachnie to złymi praktykami ale u mnie w firmie się to stosuje:
Jeśli jakieś zachowanie systemu było zmienione na życzenie klienta i na przykład związane jest z konkretną ofertą itd itp. to praktyką jest u nas by taką zmianę opisać komentarzem postaci: [data, osoba, nr oferty, komentarz]. Bardzo to pomaga zwłaszcza przy serii drobnych zmian do których nie było analizy.

Inna sytuacja : system napisany w .NET korzysta z efektów pracy SQL Server Integration Services. Nie zawsze da się sprząc zmiany w SSIS ze zmianami w kodzie tak aby zmiana dotyczyła tylko jednego miejsca i przenoisła się automatycznie z jednego mechanizmu do drugiego - wtedy komentarz postaci: zmiana w tym miejscu musi być odzwierciedlona także w systemie XY jest niezbędny IMO.