[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?

[leoha]

Komentarze to trochę taki relikt przeszłości - przydatne są w bardzo niewielu przypadkach (np dokumentacja API, wyjaśnienie skomplikowanego algorytmu i czemu wybrano właśnie ten algorytm).

@tell_me_more: no nie bardzo relikt przeszłości, skoro jak sam piszesz są przypadki gdzie są przydatne.
Ja się zupełnie nie zgadzam - zrozumienie dobrze napisane kodu i odpowiednio skomentowanego jest szybsze i prostsze. Popieram pisanie samokomentującego się kodu, ale nie popieram nie pisania komentarzy na siłę.

[ppawel]

sendUpdateAndCancelWhenTimestampVerificationFailedButNotWhenTimestampIsInThePastForMoreThenThreeMonths()

@leoha:
nawet zamieniając powyższe na:

if ( timestampVerificationFailed && ! timestampIsInThePastForMoreThenThreeMonths )

[ozzie]

ActionResult result = sendUpdate();

if (cancelNeeded(result)) {

cancel();

}

@

[Flypho]

@leoha: Weź mu powiedz jeszcze o pojedynczej odpowiedzialności metod (✌ ﾟ ∀ ﾟ)☞ bo chyba nie doszedł do tego rozdziału.

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 -

[zakopiak]

"kod ma być samokomentujący się".

@leoha: Tak, ma być samokomentujący się. Ale to oznacza jedynie tyle, że nie powinno być potrzeby pisania co kod robi. Natomiast czasami trzeba napisać dlaczego to robi.

[Vetinari]

@tell_me_more: Na przykład brak await. Chyba, że robisz synchronicznie requesty albo od razu po wysłaniu je anulujesz.

[tell_me_more]

@Vetinari: to już kwestia języka, bibliotek, architektury. Zwykle da się to ładnie podzielić (choćby korzystając z generatorów, futures, a na co bardziej upośledzonych platformach zawsze można wydzielić kod do klasy z kilkoma metodami i polami zamiast jednej dużej metody). Nie zawsze warto, ale zwykle tak.

@Flypho: i znowu wracamy do podstawowego problemu z "rozwijaniem zależności przez komentarze w miejscu wywołania" - jak chcesz pomóc czytelnikowi opisując w okolicach

[ponton]

@ozzie:

} else {

// do nothing

}

[Flypho]

i znowu wracamy do podstawowego problemu z "rozwijaniem zależności przez komentarze w miejscu wywołania" - jak chcesz pomóc czytelnikowi opisując w okolicach wywołania mocno zagnieżdżonego kodu - co robią wywoływane metody z detalami - to za pół roku komentarz będzie kłamał, bo skąd gość zmieniający metodę X ma wiedzieć, że ktoś ją wywołuje 5 poziomów wyżej (jeszcze może przez DI) i tam skomentował co robiła do tej pory?

@tell_me_more: Wybór

[Khaine]

@ponton: Hehe, szybko byś się przekonał do komentarzy jakbyś zobaczył to przez co ja przechodziłem przez ostatnie dwa dni. Jakieś 5-10 metod, które robią bardzo podobne czynności ale w nieco inny sposób i przyjmują inne argumenty. Każda ma po kilkadziesiąt linijek i używa jakichś dziwnych klas oraz funkcji, których definicji trzeba by było szukać w całym kodzie w IDE z 97 roku. Nic nie jest opisane, nic nie jest powiedziane.

[M4ks]

@leoha: każdy kto w programowaniu używa słów pt nigdy albo zawsze w odniesieniu do takich rzeczy jest debilem.

[leoha]

@Khaine: głos rozsądku...