Czy komentujecie kod?

Na wstepie zaznaczam ze nie dotyczy to komentarzy logiki biznesowej, bo te czasem bywaja nieodzowne. Pracujac przy poprzednim systemie mielismy nakaz komentowania wszystkich publicznych metod, wlasciwosci, klas itp. Do tego kazdy uzywal Ghostdoc, co konczylo sie tym ze np. metoda

GetFirstItem()

miala komentarz

Gets first item.

Chyba nie musze mowic ze dla mnie bylo to "troche" bez sensu. Argumentacja byla taka ze z komentarzy jest automatycznie tworzona dokumentacja, ale co to za dokumentacja w takim razie?

W obecnym projekcie komentarzy w zasadzie nie stosujemy w ogole. Sam czasami zastosowalem wyjatek jesli metoda wykonywala jakas bardzo specyficzna, techniczna logike i ciezko bylo strescic jej pelna funkcje w wystarczajaco krotkiej nazwie- oczywiscie metoda sama w sobie byla krotka. Czasami natrafiam na metode czy tez klase ktora ma co prawda jasna nazwe, ale brakuje jednak jakiegos dodatkowe wyjasnienia aby mozna bylo miec pewnosc co do pewnych zachowan bez analizowania kodu. Sa to jednak wyjatki.

Jak to wyglada u Was?

Swojego kodu właściwie nigdy.. Cudzy kilka razy mi się zdarzyło. Używam takiego nazewnictwa żeby od razu wiadomo było co dany fragment robi

Ja uważam, że komentarze powinny być tylko w miejscach nietrywialnych / algorytmicznych lub w miejscach gdzie jest zastosowany jakiś trik, a następnie przejrzyście opisywać "co ten kod robi".

aby nie być gołosłownym zarzucę jakimś przykładem

float Q_rsqrt( float number )
{
	long i;
	float x2, y;
	const float threehalfs = 1.5F;

	x2 = number * 0.5F;
	y  = number;
	i  = * ( long * ) &y;                       // evil floating point bit level hacking
	i  = 0x5f3759df - ( i >> 1 );               // what the fuck?
	y  = * ( float * ) &i;
	y  = y * ( threehalfs - ( x2 * y * y ) );   // 1st iteration
    // y  = y * ( threehalfs - ( x2 * y * y ) );   // 2nd iteration, this can be removed

	return y;
}

https://github.com/id-Software/Quake-III-Arena/blob/master/code/game/q_math.c#L552

lub

int BoxOnPlaneSide (vec3_t emins, vec3_t emaxs, struct cplane_s *p)
{
	(...)
	switch (p->signbits)
	{
	case 0:
		dist1 = p->normal[0]*emaxs[0] + p->normal[1]*emaxs[1] + p->normal[2]*emaxs[2];
		dist2 = p->normal[0]*emins[0] + p->normal[1]*emins[1] + p->normal[2]*emins[2];
		break;
	case 1:
		dist1 = p->normal[0]*emins[0] + p->normal[1]*emaxs[1] + p->normal[2]*emaxs[2];
		dist2 = p->normal[0]*emaxs[0] + p->normal[1]*emins[1] + p->normal[2]*emins[2];
		break;
	case 2:
		dist1 = p->normal[0]*emaxs[0] + p->normal[1]*emins[1] + p->normal[2]*emaxs[2];
		dist2 = p->normal[0]*emins[0] + p->normal[1]*emaxs[1] + p->normal[2]*emins[2];
		break;
	case 3:
		dist1 = p->normal[0]*emins[0] + p->normal[1]*emins[1] + p->normal[2]*emaxs[2];
		dist2 = p->normal[0]*emaxs[0] + p->normal[1]*emaxs[1] + p->normal[2]*emins[2];
		break;
	case 4:
		dist1 = p->normal[0]*emaxs[0] + p->normal[1]*emaxs[1] + p->normal[2]*emins[2];
		dist2 = p->normal[0]*emins[0] + p->normal[1]*emins[1] + p->normal[2]*emaxs[2];
		break;
	case 5:
		dist1 = p->normal[0]*emins[0] + p->normal[1]*emaxs[1] + p->normal[2]*emins[2];
		dist2 = p->normal[0]*emaxs[0] + p->normal[1]*emins[1] + p->normal[2]*emaxs[2];
		break;
	case 6:
		dist1 = p->normal[0]*emaxs[0] + p->normal[1]*emins[1] + p->normal[2]*emins[2];
		dist2 = p->normal[0]*emins[0] + p->normal[1]*emaxs[1] + p->normal[2]*emaxs[2];
		break;
	case 7:
		dist1 = p->normal[0]*emins[0] + p->normal[1]*emins[1] + p->normal[2]*emins[2];
		dist2 = p->normal[0]*emaxs[0] + p->normal[1]*emaxs[1] + p->normal[2]*emaxs[2];
        break;
	default:
		dist1 = dist2 = 0;		// shut up compiler
		break;
	}

	sides = 0;
	if (dist1 >= p->dist)
		sides = 1;
	if (dist2 < p->dist)
		sides |= 2;

	return sides;
}

https://github.com/id-Software/Quake-III-Arena/blob/master/code/game/q_math.c#L796

Tj: u mnie wszyscy staraja się unikać na ile to możliwe komentarzy. Założenie jest takie że komentarz jest "błędem" mniej więcej podobnie określa temat "Uncle Bob".

U mnie podejście jest takie:
W pierwszej kolejności co robi kod ma mówić sam kod tj: nazwy/zmiennych/metod itp itd. Jak jest problem żeby to skumać
to unit-testy mają mówić co i jak robi jako swojego rodzaju "dokumentacja".
Komentarz jest 3 krokiem gdy dwa powyższe nie dają możliwości bycia dostatecznie "descriptive".
I komentarze się trafiaja w miejscach gdzie robi się coś teoretycznie nielogicznego lub mało oczekiwanego.
Np: okazuje się że API innego systemu odpowiada w sposób 'totalnie z czapy' albo że jest jakiś graniczny uber-corner case który wymaga jakieś automagicznego obejścia w kodzie. Generalnie elementy kodu których byś sie nie spodziewał w tym miejscu opatrzone są komentarzem.

Nie wiem czy to podejście jest "słuszne" ale myślę że się sprawdza w mojej domenie.
No dzięki temu unikamy sytuacji gdzie pisze się w komentarzach czy docstringach "oczywiste" rzeczy.
A jednocześnie "promujemy" postawe w której unit-testy stanowią dokumentacje systemu. Komentarz ostatnia deska ratunku jak juz nic się nie da zrobic a przypadek jest "beznadziejny".

Dla porównania w poprzedniej firmie w której pracowałem ludzie byli maniakami komentarzy i proste metody na 2 linijki były opatrzone komentarzami na kilkanascie linii do tego stopnia ze z kodu szybciej szło dojść niż z komentarza. W mojej opinii dobrze to wyglądało na papierze i nie było pomocne dla nikogo defacto. Mnie to osobiście troche frustrowalo bo czulem sie jak "developer-dokumentalista" - co więcej tam ludzie promowali komentarze i docstringi wzgledem unit -testu co w mojej opinii było stratą czasu i potencjału ludzkiego. A review ciągnęło się dniami ze względu na to że ktoś uważał że "dokumentacja kodu" jest niepełna ;E

Dodam bo w sumie może mieć to znaczenie, jako zespół piszemy głównie w Pythonie czasami troszke w JS/Go.
Nie ma 'biznesu' czy jak kto woli "logiki biznesowej" klient jest 'wewnętrzny' nie generujemy żadnej 'dokumentacji' z docstringow itp itd.
Może mieć to znaczenie że projekty nasze są raczej niezbyt duże z racji wykorzystania Pythona.

Po prostu każde skrajności są niedobre i tyle.

nie nigdy, po co ułatwiać innym życie? niech trochę pogłówkują

Komentarze w 99,9% są niepotrzebne, co nie znaczy, że nie należy komentować w ogóle. Komentarze się niewątpliwie przydają w pewnych sytuacjach, podobnie jak aceton czy denaturat przydają się w pewnych sytuacjach (ale nie do picia!)

Aventus napisał(a):

Pracujac przy poprzednim systemie mielismy nakaz komentowania wszystkich publicznych metod, wlasciwosci, klas itp. Do tego kazdy uzywal Ghostdoc, co konczylo sie tym ze np. metoda

Kopiuj

GetFirstItem()

miala komentarz

Kopiuj

Gets first item.

Takie komentarze to trochę jak picie denaturatu, wymóg dawania ich przy każdej metodzie to jak wymóg codziennego picia denaturatu. Niezrozumienie tego, do czego służą komentarze.

Nie ma 'biznesu' czy jak kto woli "logiki biznesowej" klient jest 'wewnętrzny' nie generujemy żadnej 'dokumentacji' z docstringow itp itd.
Może mieć to znaczenie że projekty nasze są raczej niezbyt duże z racji wykorzystania Pythona.

Docstringi to rak. Nie dość, że traci się czas na pisanie to jeszcze zaciemnia kod oraz nie jest żadną pomocą (jakoś dziwne, że w projektach, których nawet było mnóstwo dokumentacji dosctringach do każdej funkcji i tak musiałem pytać innych programistów o to, "co ten kod robi", ponieważ dokumentacja była zbyt szczegółowa, a nie dawała big picture - co moduł X robi, w jaki sposób działa, w jaki sposób go połączyć z modułem Y. Czyli była g**no warta. Naprawdę, lepiej by było, żeby zamiast dokumentować każdą funkcję, programista opisał po prostu jakieś proste README do danego modułu.

Szczególnie, że te komentarze typu funkcja Foo przyjmuje argument X o typie string to często zwykle taka emulacja statycznego typowania. Prawda jest taka, że wystarczy dodać statyczne typowanie (np. TypeScript zamiast JavaScript*) ew. jakiś silnik inferencji typów i ma się o wiele większą moc w IDE czy czasem już na poziomie wykrywania błędów w kompilatorze. No i sama nazwa parametru dużo zmienia. Ludzie piszą jak głupi komentarze, a wystarczy nazwać parametr w taki sposób, żeby było wiadomo do czego służy.

* (hejtuję statyczne typowanie, ale rzeczy typu JSDoc są jeszcze gorsze, bo to statyczne typowanie dla ubogich).

Hej,
przy krótkich kodach nie komentuję, i nazwy zmiennych raczej mam krótkie, szczególnie jak są pomocnicze, iteracyjne, itd. Przy dłuższych kodach czasem sadzę komentarze, staram się pisać nazwy funkcji tak, aby one coś mówiły, ale największą uwagę zwracam na czytelność kodu, odstępy, wcięcia, to bardzo dużo daje. I bardzo nie lubię ZmiennychKtóreMająDługąNazwęIWieleCzasuTraciSięNaOgarnięcieTakichZmiennychSzczególnieJakJestIchKilkadziesiątAlboKilkaset :)

Jestem za komentowaniem nawet prostych fragmentów programu i nie rozumiem dlaczego miałby to być błąd. W programowaniu funkcyjnym, które ostatnimi czasy jest tak uwielbiane komentarze są wręcz konieczne...

Jeśli używa się dziwnych znaczeń, to lepiej jak są komentarze.

Przy takim programowaniu gier, gdzie wszystko ma swoją klasę jako oddzielny skrypt i nie ma tam żadnych niezrozumiałych sformułowań, to taki kod czyta się z przyjemnością, a znajduje co potrzeba błyskawicznie.

W innych technologiach to może być już różnie, ale podstawa to dobra struktura katalogów i hierarchia klas.
Wtedy każdy element układanki jest prostą klasą.

Chodź przy reverse engineeringu też bez problemu da się rozkodować nawet trudne algorytmy matematyczne, chodź wydaje się że czasem jest łatwiej niż w spaghetti kodzie, chodź czasem jedno i drugie wygląda jak refaktoryzacja, z czego pierwsze ma lepsze narzędzia dostępne :>

U mnie stosujemy zasade, że każda metoda powinna mieć komentarz odnośnie danych wejściowych i wyjściowych, w sensie na wejście nazwa + typ, i na wyjście typ, bo często po kodzie nie widać co to za dane szczególnie w językach dynamicznie typowanych. Natomiast co do typowego komentarza to jeśli ktoś wie, że po nazwie metody inna osoba może mieć problem zrozumieć co się dzieje no to warto dać opis. Zresztą mówicie, że "nie na co opisy" a jak zaglądam do jakiejkolwiek biblioteki/paczki na githubie to każdy fragment kodu jest porządnie opisany.

@Srebrny Wąż

d. W programowaniu funkcyjnym, które ostatnimi czasy jest tak uwielbiane komentarze są wręcz konieczne...

Może jakieś przykłady na tak ciekawe zdanie? Albo:

@mr_jaro

U mnie stosujemy zasade, że każda metoda powinna mieć komentarz odnośnie danych wejściowych i wyjściowych, w sensie na wejście nazwa + typ, i na wyjście typ,

No to odkryliście system typów. Faktycznie jest przydatny. Niektóre języki mają to wbudowane i taką informację używa kompilator do dodatkowego szukania błedów, a IDE do podpowiadania kodu.

Trochę linków:
https://refactoring.guru/smells/comments
https://softwareengineering.stackexchange.com/questions/1/comments-are-a-code-smell
https://simpleprogrammer.com/why-comments-are-stupid-a-real-example/

Jak ktoś wierzy, że pomaga komentarzami, javadocami i innymi docami to niech wie, że duża część programistów po latach oglądania korpokodu wyrabia sobie wręcz magiczna zdolność nie czytania/ ignorowania komentarzy. Lata rozczarowań (komentarza kłamia) powodują, że kommenty nie trafiają nawet do podświadomości.

Są wyjątki oczywiście:

Komentarze przy bardzo dziwnej logice link z numer emdo JIRY /Taska. Kod pokazuje co robi, ale czasem nie wiemy dlaczego. Biznes wymyślił coś tak głupiego, że trzeba to podlinkować Zwykle jest to cała historia w zadaniu. Nie ma sensu tej historii wklepywac w kod.

Czasami przegrywamy. Bywa tak, że na danym poziomie kodowania nie umiemy czegoś rozsądznie nazwać, poprawić i wtedy wsadzamy komentarz. Takie poddanie się powinno być wyjątkiem. Jeśli się często zdarza to albo używamy za słabego języka, albo jesteśmy trochę za słabi. W drugim wypadku warto poćwiczyć, poprosić o radę. Mi często na review koledzy pomagają nazwać rzeczy dużo lepiej niż w oryginale i potrzeba komentowania znika.

Co do słabego jezyka : w assemblerze niestety trzeba sadzić kommenty (nawet jak mamy dużo makr). W C chyba też czasem trzeba :-(, w JS trudno mi powiedzieć. NIe komentuje, ale raczej staram się JS unikać (TS , ScalaJS). W Whitespace także trudno obejśc się bez komentarzy.

Co do oryginalnego problemu : to wymuszone komentarze ( np. przez review i jakiś tool na CI) to najgorsze bagno. Z tego wychodzi najbardziej nonsensowena, łżąca paplanina, zaciemniająca kod.
Może strolujcie to jakoś : wstawiajcie jako kommenty: kod, lorem ipsum, pseudokod w algolu 68 albo w basicu :-), rymowanki.

Mój stosunek do pisania komentarzy najlepiej streszcza ten cytat:

"Code can describe how, but it cannot explain why."

i dołączona do niego historyjka:

które pochodzą z artykuły The Art of Comments ,
podsumowując, wszelkie komentarze które są w stanie przekazać to czego nie jest w stanie przekazać dobrze napisany kod, są jak najbardziej wskazane.

Brakuje mi tu jeszcze jednego przypadku. Komentarz streszczenie: Ta klasa służy do ... Jej główną metodą jest ... Piszę takie komentarze i chciałbym, żeby inni też je pisali. Inaczej trzeba studiować parę stron kodu, żeby załapać ideę.

Może ktoś powie: to nazwij klasę odpowiednio. Ale nazwy klas muszą być krótkie i siłą rzeczy nie zawsze będą samowyjaśniające się.

Czytam ostatnio "Clean Code" Robert C. Martin.
Tam jest cały rozdział o komentarzach. Krótkie streszczenie:

• małe funkcje z dobrymi nazwami są lepsze od komentarzy
• komentarze mogą kłamać (kod został poprawiony, a komentarz nie został zaktualizowany, a żaden automat nie sprawdzi komentarzy, poza Java Doc/Doxygen)
• komentarzy powinno być mało
• komentarze nie powinny: owijać w bawełnę, opisywać oczywistego, być tylko po to by wypełnić jakieś wymagania, opisywać historię kodu, straszyć, być dekoracyjne, zawierać kod
• komentarze powinny:

Polecam lekturę IMO warto. Pdf bez problemu można znaleźć w sieci.

Komentarze w sensie javadocków w aplikacji są moim zdaniem bezsensowne. Czasem trzeba może napisać komentarz wewnątrz metody dlaczego coś zrobiliśmy tak a nie inaczej, ale powinien to być wyjątek a nie rutyna.

Javadocki mają jako taki sens dla bibliotek. Bardzo cenię sobie javadocki do RxJavy, bo często nie muszę komuś tłumaczyć jak działa jakiś operator, tylko mogę mu powiedzieć, żeby nacisnął Ctrl + Q. Nie chciałbym natomiast zajmować się utrzymywaniem takiego kodu. Istny koszmar dla programisty. Lepszym rozwiązaniem wydaje mi się readme i przykładowy kod jak korzystać z blibloteki, jeżli ktoś ma jej zacząć używać.

Dorzuce jeszcze troche odnosnie pkt 2 z powyszego posta ("ze swojego doświadczenia") ze jesli dodajemy do kodu komentarze/docstringi to teoretycznie "powinny" być one ogólne/generyczne w tym sensie żeby w komentarzu unikać hardkodowania konkretnych nazw zmiennych/klas/metod (jesli to mozliwe).

czyli np: zmiana nazwy metody/zmiennej itp na ogół nie powinna wymuszac koniecznosci zmiany docstring-a - spotkałem się z przypadkiem gdzie ludzie w docstringach pewnych metod używali nazw własnych czy nazw zmiennych innych metod. Nie muszę mówić że potem przy zmianie czegoś należało zmienić docstringi w wielu metodach. Oczywiście na review był "Cerber" który tego pilnował ale było to "słabe" i może pomysł czy idea nie były złe ale mało pragmatyczne.

Ów pragmatyzm wynika z tego że: developerzy sa leniwi(powinni być :P) | developerzy nie chca /nie lubia/ zapominaja edytowac docstringi po zmianach i tak robi sie balagan opisany w pkt 2

(troche bzdurny przyklad ale wlasnie mi przyszedl do glowy)
Chcemy zainstalowac klucz publiczny na remote serwerze (wczesniej wygenerowalismy klucze lokalnie ofc) zeby smigac po ssh.

Ktos napisal mniej wiecej cos takiego (pseudokod).

def send_public_key_from_local_path_to_remote_server(local_path, 
remote_user_login, remote_user_password, remote_server):
    """Copy locally generated ssh keys from local_path to remote_server with 
        using remote_user_login account.  """ 
    cmd = "ssh-copy-id -i {} {}@{}".format(local_path, remote_user_login ,remote_server)
    run_ssh(cmd)
    ...

Ktos bardziej leniwy od poprzednika w to zajrzal i zlapal sie za glowe i mysli omg "Co za pracowity Janusz":
I zabral sie za zmiany i zmienił nazwe funkcji i nazwy zmiennych ogolnie uznal ze lepiej haslo i login
wysylac np: jako jeden obiekty 'credentials' i nawet zmienil to w docstringu ->
extra uznal ze w zasadzie wszyscy z reguly uzywaja kluczy ze sciezki domyslnej wiec mozna
miec metoda z mniejsza ilosc zmiennych.
Ale nieborak zapomnial zmienic nazw wszystkich zmiennych w docstringach zagapil sie jakos mu umknelo wystawil MR
poszlo do review ;D

def send_public_key(path=None, credentials, server):
    """Copy locally generated ssh keys from local_path to remote_server 
        with using credentials.  """ 
    path = '/home/.ssh/id_rsa.pub' or path
    cmd = "ssh-copy-id -i {} {}@{}".format(path, credentials.login ,server)
    run_ssh(cmd)
    ...

Za review i mergowanie odpowiedzialny jest junior bo Lead jest w Teamie jeden
i akurat jest na urlopie i wroci za 3 tygodnie a wiadomo robota musi iść do przodu.
I BANG "Merge" bez zadnych zmian.

Po 3 tygodniach wraca Lead i przeglada Merge i trafia na ten temat i widzi rozjazd a ze Lead to pewnie sie zna to sobie mysli tak:
Jest rozjazd w docstringach nie zgadzaja sie nazwy zmiennych z rzeczywistym:

I robi TAK:

def send_public_key(path=None, credentials, server):
    """Copy locally generated ssh keys to remote server. """ 
    path = '/home/.ssh/id_rsa.pub' or path
    cmd = "ssh-copy-id -i {} {}@{}".format(path, credentials.login ,server)
    run_ssh(cmd)
    ...

No i sobie mysli bedzie git teraz jest generycznie i nie ma bledow i rozjazdu... no ale mysli myśli myśli
Nazwa funkcji w sumie jest OK i mowi co robi wiec docstring nic nie wnosi.
Każdy wie jak dziala "ssh-copy-id" na Linuxie i po co to pisać.

Sobie mysli Jestę Lead Developerę i zrobię CIACH
i dopiszę unit testy !

def send_public_key(path=None, credentials, server):
    path = '/home/.ssh/id_rsa.pub' or path
    cmd = "ssh-copy-id -i {} {}@{}".format(path, credentials.login ,server)
    run_ssh(cmd)
    ...

Przyklad wziety 'z czapy' i mega uproszczony (trzebaby poprawic) ale podobny mechanizm działania widzialem już wiele razy na dużo większą skalę i w dużo bardziej "zaawansowanych" przykładach gdzie ludzie wykonywali nikomu nie potrzebną pracę w komentarzach - nikt tego nie czyta calosc tylko zaciemnia i doklada robote na 'maintenance'. Lepiej poswiecic czas na dobre zmienne nazwy czy dopracowanie unit-testow albo dopisanie kilku scenariuszy testow integracyjnych zamiast tracic czas i zapal na docstringi.

Komentarze mam ostylowane jako czarny tekst na błękitnym tle.
Przeważnie używam ich tak:

// === dzida =============
// --- przeddzidzie ---
...
// --- /przeddzidzie ---

// --- śróddzidzie ---
...
// --- /śróddzidzie ---

// --- zadzidzie ---
...
// --- /zadzidzie ---
// === /dzida =============

Bez właściwego kolorowania to nie wygląda jak powinno, ale w każdym razie idea jest taka, że stanowią nagłówki bloków, więc szukając czegoś wystarczy przelecieć wzrokiem po tych nagłówkach. Odmienne tło, sprawia natomiast, że nie rozpraszają mnie przy oglądaniu właściwego kodu, bo wtedy postrzegam je jako coś w rodzaju ramek. Komentuję pętle, instrukcje warunkowe itp.

Czasami komentuję też pojedyncze linie:
kod kod kod; // robi XYZ
kod kod kod; // używa A nie zaś B, bo to i tamto

Przewaznie nie, ale zdarza sie, ale jak zwykle to zalezy:

• jak robi sie workaround do bledu w czyms zewnetrznym, bibliotece, usludze itp.
• obliczenia matematyczne, mocno optymalizowany kod, przesuniecia bitowe, wstawki w asm (ale to juz dobrych pare lat nie robilem)
• czasami w prototypach by potem pamietac co gdzie jak po co itp. bo tam zwykle pisze paskudny kod, byle szybko cos sprawdzic.
• jak sie naprawia jakies dziwne zachowania w legacy codzie albo dziwnych technologiach. Przyklad system gdzie sporo logiki bylo w XSLT. Tam mozna zapomniec o pokryciu testami i po prostu nie da sie ladnego przejrzystego kodu napisac. Czasami trzeba cos zmienic naprawic w takim projekcie - zombie, gdzie nie ma czystego kodu, pokrycia testami, a robienie z tego clean code nie ma najmniejszego sensu, tam tez komentarze sie przydaja.
• jak robie cos duzego czasami dodaje sobie tymczasowe komentarze, ale w docelowym commicie one nie ida do repo.

duża część programistów po latach oglądania korpokodu wyrabia sobie wręcz magiczna zdolność nie czytania/ ignorowania komentarzy

Fakt, jak widzę JSDoc to go nie czytam zwykle. Po prostu więcej ogarnę z kodu niż w komentarza.

Dla mnie komentarze powinny być traktowane jak reszta kodu - czyli powinno się pisać wtedy, kiedy coś wnoszą (np. tłumaczą kawałek kodu, który może być niejasny), a nie żeby pisać, bo ktoś tak każe albo dlatego, że "tak wszyscy robią" (np. "wszyscy piszą g**no dokumentarze z opisem parametrów do każdej funkcji bo tak jest profesjonalnie, róbmy tak!"). Cargo cult komentarzy, żeby wyjść na profesjonalistę, który pisze ładną dokumentację... bez sensu.

No i też źle się stało, że dokumentacja miesza się z kodem. Jakbym ja robił system do generowania dokumentacji (może kiedyś zrobię), to chyba bym zrobił tak, że dokumentację by się pisało w osobnych plikach (np. Markdown z jakimś dodatkowymi metadanymi) a nie mieszało z kodem produkcyjnym.

Czy Ja komentuje kod...?

Oczywiście!! Zawsze na głos przy otwartym oknie tak żeby wszyscy słyszeli.

Można dokumentację zrobić, z dobrą grafiką w webie, żeby się lepiej czytało i te komentarze można pominąć.
Będą wiedzieć jak działa i jak to wykorzystać, a jak będą chcieli wiedzieć w jaki sposób rozwiązali problem to już sami będą analizować.

https://twitter.com/Nick_Craver/status/1030792400837509120

Afish napisał(a):

Nick_Craver/status/1030792400837509120

przywołując Einsteina - jeśli ktoś nie umie czegoś opisać prosto to znaczy że tego dobrze nie rozumie

widziałem projekty w którym proste rozwiązania były bardzo przekombinowane i trudne, widziałem też projekty napisane genialnie gdzie trudne rzeczy stawały się trywialne nawet dla początkującego programisty dzięki dobrej architekturze

za radą wujka Boba staram się sprowadzać metody do nie więcej jak trzech linii (!) i nie korzystać z komentarzy - jeśli masz ochotę coś skomentować to zazwyczaj (choć nie zawsze, np w przypadku algorytmów) - lepiej zaznaczyć komentowany fragment kodu i wydzielić go do osobnej metody przy czym nazwa metody staje się komentarzem. Metody prywatne to zazwyczaj ukryte klasy, które powinno się również wydzielić. Przy takim podejściu za darmo dostajesz SRP.
Choć napisanie algorytmu w czytelnych trzech/czterech liniach wymaga dużo więcej myślenia niż zrobienie tego samego w 20 i oczywiście nie zawsze jest na to ochota lub czas.

staram się za to komentować wszystkie publiczne metody interfejsu opisując do czego służy klasa i poszczególne metody, jakiego zachowania można oczekiwać od metody, zwłaszcza jeśli nie jest to jasne bo skrajne przypadki często by było opisywać w nazwie samej metody;
traktuję kod jakby miał się w każdej chwili stać biblioteką bo w praktyce bardzo często się to zdarza w miarę rozrostu projektu - oczywiście tylko dobrze napisany kod może łatwo stać się biblioteką, dlatego jeśli komuś się takie coś nie zdarzyło to nie ma się czym chwalić