Komentarisanje koda - šta je pisac hteo da kaže

Komentar je “neuspeh” pri izražavanju kodom.  Ako niste uspeli [da se jasno izrazite], napišite komentar; ali težite da ipak uspete.
Robert C. Martin 

Komentari koji objašnjavaju

Legendarni “ujka Bob” je možda prestrog, ali generalno, ne možemo da zanemarimo njegovo iskustvo i otisak koji je ostavio na zajednicu programera (koji žele da pišu bolji kod). U “divljini” ćemo često sresti komentar na nekoj zamršenoj petlji ili možda iznad neke funkcije. Komentar pokušava da nam otkrije šta je pisac zapravo hteo da kaže. Uglavnom glase nešto poput “ovde se poziva x servis da bismo saznali trenutno stanje y dela aplikacije” ili možda, “ovaj uslov znači da se radi o xy tipu kupovine i onda vršimo redirekciju onamo”.  

To su naravno sasvim zdravo-razumski i krajnje dobronamerni komentari koji objašnjavaju našem kolegi šta smo radili, ali su mahom suvišni. Naime - ako naziv funkcije nije jasan sam po sebi, verovatno treba preimenovati funkciju, a ne ostaviti komentar. Zatim, možemo ići korak dalje - ako funkcija radi previše stvari da bismo je jasno imenovali, definitivno je treba razbiti na više funkcija čija je uloga dovoljno jasna da mogu da se jasno imenuju.   

Ovo neminovno znači da ćemo imati i petlje koje razlučuju koja funkcija se poziva. Uslov petlji, ukoliko već nije jedna, dobro imenovana varijabla - treba to da postane [jedna DOBRO imenovana varijabla]. Svaka logika u uslovu petlje je suvišno ometanje procesa razmišljanja, možda čitalac koda pokušava da shvati GDE kod ide dalje, a ne nužno ZAŠTO ide dalje. ZAŠTO treba da je skriveno iza jedne, posebno definisane varijable koja ima glagol u sebi, bilo da je to “should”, “show” ili neka druga slikovita apstrakcija toga što se dešava “iza kulisa” (nekad samo par redova niže ili više). 

Komentari u vezi sa biznis odlukama  

Takođe čest komentar u velikim timovima je “Kada osoba x uradi y, tada treba da izvršimo ovu implementaciju drugačije - ovo je privremeno rešenje.” Naizgled korisna informacija, može sledeće nedelje da postane dezinformacija.  Ukoliko se neke biznis odluke promene, ili donesu nove, sumnjam da ćete pohrliti da git commit-ujete ispravku svog pređašnjeg komentara koji može da stoji u bazi koda dve do tri nedelje, a neretko i duže (sretao sam ovakve komentare stare i po godinu dana). U ovakvim slučajevima, možemo koristiti pridev “temporary” ili jednostavno, samo jasan naziv funkcije, s tim da ona na kraju povlači varijablu koja će se zvati “dummy”, “mock”, “alwaysTrue” ili nešto slično, što jasno daje do znanja da ovo nije “prava” vrednost neke kalkulacije (ukoliko stvarno koristimo lažne vrednosti, a ukoliko je privremena implementacija “realna”, imenujemo stvari “normalno”). Biznis odluke treba da su definisane u kriterijumima unutar softvera za upravljanje projektima, a ne unutar našeg koda. 

Komentari “TODO” 

Ništa me ne razočara kao “TODO” komentar u development (ili ne daj Bože master) grani koda. Opet, ako nešto nije obuhvaćeno tvojim zadatkom, to treba da se reši unutar softvera za upravljanje projektom. Ako nisi u nekoj ličnoj grani, ili ne radiš na nekom ličnom projektu, postoji jako malo situacija gde “TODO” komentar treba da stigne u neku od glavnih grana koda. U toku rada, naravno, svaki bolji IDE ima dodatke koji vam dozvoljavaju da vidite gde stoje vaši “TODO” komentari. Oni mogu biti koristan alat, ali je činjenica da, ako sretnem tuđ “TODO”, pogotovo ako ta osoba nije više član tima - šanse su da je “TO DO” zapravo klasičan “TO NEVER DO”. 

Komentari koji nam objašnjavaju kako da postavimo aplikaciju da bi nešto uradili 

Za ovu svrhu svaki “kršten” repozitorijum ima README.md fajl. 

Komentari testova 

Testni kod, iako ne ide u produkciju treba da prati sva pravila čistog koda koja čine komentarisanje suvišnim. Testni kod i tek kako treba da ima jasno definisane “utility” funkcije i funkcije postavke, jer - jedina stvar gora od previše provedenog vremena na tumačenju nekog koda je, previše provedenog vremena na tumačenju koda koji služi za testiranje koda. 

Komentarisan kod 

I sam kod može biti “komentarisan”, i tako spremljen za kasniju upotrebu. Ovo bi naravno bilo korisno, kada ne bismo koristili version control softver (git) na našem projektu. Ako to nemate na projektu, komentarisan kod je vaš najmanji problem. 

Zaključak 

U nekim slučajevima, i u nekim delovima procesa, iza 7 mora i iza 7 gora, postoje slučajevi gde je apsolutno neophodno ostaviti komentar. ALI, ukoliko vaš kod nije jasan na prvo čitanje, ili recimo, realno, ako niste vešto sakrili nejasan kod iz prometnih, vidnih putanja, nemerljivo bolji izbor je vratiti se na problem i pokušati sa novim imenima varijabli i funkcija, nego samo napisati komentar i pogurati kod dalje.   

Programirajte uvek kao da ćete na tom radnom mestu ostati godinama, i da ćete baš vi biti tu, kada se biznis logika okrene naopako, sve druge kolege odu na letovanje, i produkcija padne.