[leoha]

#programowanie
W zaprzyjaźnionym teamie, z którym współpracuję jest sobie taki team lead, który bez zrozumienia przeczytał "Czysty Kod" i zakazał pisania komentarzy w kodzie bo "kod ma być samokomentujący się". Czysty debilizm, żeby zakazywać całkowicie.
Dziś oglądam repo, a tam mniej więcej takie kwiatki:

public void ActionResult sendUpdateAndCancelWhenTimestampVerificationFailedButNotWhenTimestampIsInThePastForMoreThenThreeMonths() {

A co wy sądzicie o pisaniu komentarzy w kodzie?

[z.....a]

@leoha: lol. co xD jak coś jest dziwnego w kodzie to pisze w kodzie , jak nie to piszę tylko w docstringu ogólna idee np funkcji i elo.

[cevilo]

@leoha: zarzutka jak nic, nie wierzę :)

[Kuriozal]

@leoha: wystarczy podzielic cialo metody na logiczne, ladnie nazwane male metody i bez komentarza sie obejdzie ;>

[tell_me_more]

A co wy sądzicie o pisaniu komentarzy w kodzie?

@leoha: czasem trzeba, ale niekoniecznie w tym przypadku, który podałeś. Komentarze z resztą nie są do tłumaczenia co się dzieje, tylko dlaczego się dzieje.

Nazwa metody przegięta oczywiście, do tego pewnie za parę miesięcy będzie myląca (bo dojdzie warunek albo się zmieni, że nie po 3 miesiącach tylko po miesiącu). Ja bym nazwał tą metodę sendUpdateAndCancelWhenNeeded(). Jeśli w ogóle musi to być

[Vetinari]

@tell_me_more: Na przykład co robi cancelNeeded? Kiedy jest needed? Jakby był komentarz, to byś miał w komentarzu, jak nie ma musisz przejść i sprawdzić kod.

[wnocy]

@leoha: problem z komentarzami jest taki, że kod się zmieni, a komentarz zostanie stary. Dodatkowo (tak jak poprzednik pisał) komentarz musi tłumaczyć dlaczego coś zostało rozwiązane tak, a nie jak to działa, bo to na ogół widać na pierwszy rzut oka (chyba, że właśnie piszesz quake i wymyśliłeś szybką odwrotność pierwiastka). Kilka razy w życiu mi się zdarzyło, że patrzyłem na swój kod myśląc "boże, dlaczego ja to tak zrobiłem, zaraz

[mathix]

@leoha: Wszystko w porządku jeśli piszecie kod w Objective-C XD

[tell_me_more]

@Vetinari: Ctrl+click i wiesz kiedy cancelNeeded. A jak napiszesz to raz w komentarzu, albo w nazwie metody - a drugi raz w kodzie to potem ktoś zmieni w kodzie a zostawi w komentarzu i będzie zmyłka. Miałem takie sytuacje na tyle często, że uważam, że to ZŁO - detale co robi kod powinny być w jednym miejscu - w kodzie.

[leoha]

problem z komentarzami jest taki, że kod się zmieni, a komentarz zostanie stary.

@wnocy: to tak jak z nazwami metod czy zmiennych, kod się może zmienić, nazwa zostanie stara...

[ponton]

Jakby był komentarz, to byś miał w komentarzu, jak nie ma musisz przejść i sprawdzić kod.

@Vetinari: I tak byś musiał sprawdzić kod, bo nie masz pewności, że komentarz jest aktualny.

[tell_me_more]

@leoha: dlatego nazwy trzeba nadawać na odpowiednim poziomie abstrakcji. Nie ma potrzeby powtarzać w nazwie metody każdej jej linijki. Wystarczy ogólny zarys co ona robi, żeby czytelnik wiedział, do której metody zajrzeć, jak będzie potrzebował szczegółów.

Z innej beczki - ja nawet jak komentarz jest potrzebny to wolę dodawać je w formie komentarzy do komitów, niż komentarzy w kodzie. Bo dzięki temu widać dokładnie do których linijek kodu ten komentarz się

[wnocy]

@leoha: z nazwami metod jest trochę inaczej. Metoda wykonuje jakieś konkretne zadanie np. passwordReset i małe są szanse na to, że to się zmieni. Natomiast to jak ona to będzie robiła może się zmieniać z czasem. Bo może wysłać maila, albo smsa, albo zapytać o stare hasło, itd.

Zresztą wracając jeszcze do komentarzy - dzisiaj większość kodu to taka mechaniczna robota. Nie ma tu żadnej finezji, przez co "z nudów" wymyślamy

[Vetinari]

@ponton Jeżeli nie jest aktualny to błąd zrobił ten, kto zmienił metodę, a komentarza nie poprawił.

[biwalencik]

@leoha

(╯︵╰,)

[ponton]

@Vetinari: Czyli jak zmieniasz metodę foo(), to potem musisz szukać wszystkich wywołań tej metody i patrzeć, czy czasem ktoś jej tam nie skomentował? Przecież to absurd.

[Vetinari]

@ponton: Ale wiesz że metody się komentuje nad deklaracją a nie w kodzie przy wywołaniu?...

[ponton]

@Vetinari: W życiu czegoś takiego nie widziałem, a trochę już pracuję jako programista. Chyba że mówisz o doxygenie, to tym bardziej nie ma to sensu, bo zamiast szukać deklaracji lepiej od razu iść do definicji.

[Vetinari]

@ponton: Jak metoda ma 200 linii i oblicza jakiś hash to lepiej sprawdzić jakie działania matematyczne wykonuje czy napisać komentarz?

https://github.com/AFNetworking/AFNetworking/blob/master/AFNetworking/AFHTTPSessionManager.h

[tell_me_more]

@Vetinari:

Komentarze z deklaracji pojawiają się w miejscu wywołania w chmurce, jak najedziesz na nazwę metody. Klikając z ctrl skaczesz do metody i widzisz kod i nie musisz się zastanawiać, czy komentarz jest aktualny, albo co się dzieje w nieopisanym corner case. Z resztą - można sobie skonfigurować IDE, żeby w tej samej chmurce wyświetlało kod metody na którą najechałeś i skakać nie trzeba, jeśli Ci to przeszkadza :)

Oczywiście zdarzają

[ponton]

Jak metoda ma 200 linii i oblicza jakiś hash to lepiej sprawdzić jakie działania matematyczne wykonuje czy napisać komentarz?

@Vetinari: Właśnie o to chodzi, żeby nie pisać metody na 200 linii, tylko proste i czytelne funkcje, których nie trzeba komentować. Komentarz to jak przyznanie się do błędu, że nie umiało się tego prosto zaimplementować.