[POLEMIKA] Komentovať alebo nekomentovať.

Ja osobne zastavam nazor ze komentovat by sa malo len to, co sa neda povedat kodom. Tj. kod by mal popisovat co robi a programator by mal - ak je to potrebne pridat "preco". Vacsina komentarov "co" sa da odstranit jednoducho -> refactor : extract method a nazov metody/funkcie je popis danej funkcionality. V pripade ze sa neda najst rozumne meno pre danu funkciu si treba dat otazky: Nerobi ten kod prilis vela ? Dokazem ten kod napisat inac - tak aby bolo zrejme co robi ?
Dalsi aspekt je "udrziavanie" komentarov. Zly, resp. neaktualny komentar je horsi ako ziadny.

Moj nazor je: Snazit sa minimalizovat pocet komentarov na minimum, pretoze mozu vytvarat "noise" v kode a mozu byt naznakom "code smells". Snazit sa napisat kod tak, aby bol pochopitelny a rozpraval urcity "pribeh".

Ja zasa komentujem podla nalady, ked mam dobry den, tak je kazdy riadok s komentarom, ked je zly, tak su komentare len generovane ghostdocom:)

Ale nie, obcas su komentare precenovane, urcite su nutne, najma ak je vo funkcii nejaky algoritmus, ale obcas sa popisuju na popisovanie samopopisujuceho. A obcas je to len neschopnost programatora nazvat spravne premennu. Milujem najme temp, temp1..n, var1..n, prem, prem1..n.

Pre prehlad v kode je dolezity aj indent, zalamovanie riadkov, oddelenie riadkov logickych celkov kodu, obcas som sklamany s resharpera ako neinteligentne zalamuje riadky.

asi sa tu zhodneme, ze komentovat kazdy riadok je blbost.. vacsinou teda staci ghostdoc + nejaka gramaticka uprava. mozno aj to je zbytocne, ale intellisense potom vyzera krajsie :)

ale urcite komentujem algoritmy, aspon minimalne pomenujem, ze tu je implementovany taky algoritmus. ale hlavne komentujem podmienky, ktore nie su uplne jasne, lebo su pouzite len v nejakom kontexte. Urcite je jednoduchsie cita
// ak su deti cierne a bratranec cierny, tak treba spravit vyvazenie podstromu
asi som napisal blbost, ale uz si nepamatam R-B tree :)

ale napada ma otazka. v akom jazyku pisete komentare, pokial zakaznik nema na to poziadavky.

ja sa snazim v anglickom. hlavne po tom ako som raz pocul prihodu, ze niekto prebral kod od talianskej firmy. tam bol problem, ze este aj premenne a metody boli v taliancine.

Ja som za anglictinu, ale projekt na ktorom robime je urceny pre zahranicie a tam by stacktrace v slovencine nevyzeral dobre. Na druhu stranu, ked som pracoval na mzdovom software, tak sme po urcitej dobe (cca 1 rok, predtym sa robili core veci, tak to az take horuce nebolo) prisli na to, ze pisat komentare v anglictine pre specificke vypocty pre slovensko moc zmysel nema. Urcite ale aspon minimalne by som nedaval diakritiku do nazvov tried a metod.

co je lepsie ?

komentar:
// ak su deti cierne a bratranec cierny, tak treba spravit vyvazenie podstromu

alebo
kod:
if (deti.AreBlack() && bratranec.IsBlack())
VyvazPodstrom();

- kod vacsinou neklame, comments mozu
- samozrejme tu exsituje otaza: do akej miery su podobne "zmeny" prospesne pre citatelnost kodu ?

Najhorsie je mat totalny mix: SlovenskoAnglicke metody + hungarian Notation

GetUzivatel(), objFirstUzivatel, ComputeMzduZamestnanca, intCountObjektov

Ja preferujem len jedno : Anglictinu. Problem nastava v pripade ako pise Vlko: ked mame dajake specificke veci, ktore sa len velmi tazko opisuju v anglictine.

@rebro.. ja viem, ze som neuviedol asi najlepsi priklad. trochu mi to pripomina, ked sme sa ucili dokazovanie spravnosti programov. tiez sme sa to ucili na jednoduchych prikladoch, kde cely dokaz spravnosti v podstate spocival v prepisani do matematickeho modelu s trochu inou semantikou. dokonca pre jednoduche priklady sa dala ta semantika povazovat za zhodnu, takze to bolo len hlupe prepisovanie do ineho jazyka, a preto nikto nechapal, v com spociva dokaz spravnosti.

lenze pre zlozitejsie algoritmy uz invarianty nemuseli byt take zrejme. teda pre toho, co algoritmus vymysla aj ano, ale nie pre toho, co ho cita. takze, aby som upresnil svoj nazor na komentare, tak sa snazim pisat do komentarov invarianty, ktore nie su z kodu uplne zrejme. takisto pisem preconditions, ktore sa v kode vobec nevyskytuju, lebo su dane algoritmom alebo by design. napriklad to, ze bratranec.IsBlack() mozes testovat o 20 riadkov vyssie alebo inde v callstacku, ale pre volanie VyvazPodstrom() to je kriticke, tak to do komentara napisem.

a posledna vec, co komentujem, ak mi nieco nefunguje a musim spravit hack, tak napisem, ze aky hack a preco bol tak spraveny. aby sa nestalo, ze pride mudrlant a pozrie, ze co je to za otrasny kus kodu, tak to prepise a zisti, ze mu to nefunguje.

inac uz sa mi parkrat stalo, ze komentare mi posluzili ako dokaz spravnosti. ja totiz najprv pisem kod a potom ho komentujem. no a pritom nie je problem zistit, ze v kode je nieco ine napisane ako v komentari. takto mam chyteny bug bez debugovania :)

@Duracelko:
pri dobrej enkapsulacii a OOD naozaj budes tazko hladat dobry priklad.

Bohuzial, na dobru encapsulaciu nie je vzdy cas alebo nie vzdy sa oplati a ked chces pomoct kolegom, tak im nejaky kus kodu, kde robis nejaky zazrak v bloku kodu okomentujes ... dostanes ich tak lahsie do kontextu. Mozno na to si sa snazil poukazat. Vlastne ani mne sa nechce lustit nejaky x riadkovy linq magic o tyzden, co som v zachvate geniality nieco inline zbuchal, ked si dam hint cez komentar, urcite to rozlusknem lahsie.

A napr. osobne preferujem blok kodu pred jednoucelovym vytvaranim metody[a specialne privatnej v samotnom objekte], lebo potom citatelnost kodu pada na tomto a na nutnosti masivnej navigacie po nom nehovoriac o neefektivite z vnarania.

@rebro:
ak je slovensky zakaznik a komunikujete v slovencine, je aj tak narocne udrziavat dva jazyky / dve terminologie - jeden v teame a jeden na vonok a prepinat sa medzi nimi.
Nevyhodou su potom take mix slova(co znie horsie ZákazníkRepository alebo uff ...RepozitarZákazníkov...a to som sa celkom vynašiel monestifikovaným ekvivalntom slova) ...prosto nevidim to tak tragicky ako hungarian notation ;-)

@T: ano.. pri spravnom OOD sa tazko hlada vhodny priklad. Lenze nie vsetky problemy sa dobre riesia OO paradigmou. Prave preto je tu F# :)

ale presne ako hovoris, nie vzdy sa oplati davat jednoucelovu vec do private metody. a ak aj ano, tak v private metode netestujem preconditions, pretoze su private a inde zabezpecujem aby boli splnene. ale zato ich napisem do komentara, aby som po case na prvy pohlad videl ze metoda funguje (alebo aj nefunguje :) vo vsetkych pripustnych pripadoch.

dalsia vec ma napada, ze ak sa naozaj rozsiri viac paralelne programovanie, tak niektore veci budu este menej zrejme, kedze nebudu ovplyvnene len par riadkami pred/za komentarom, ale aj kodom v inej metode na inom threade.

@duracelko: Aj funkcionalny pristup umoznuje riesit pekne enkapsulaciu, takze ani tam nie je problem.

Poslite SMS: BIG_1949457 na cislo: 7604 Potom Vam system prideli nick a heslo, posle Vam adresu webu na ktorom si potom mozete pozerat bonusovy obsah. Cena SMS: 0,35€