Opět jsem se setkal s názorem, že komentovat zdrojové kódy není potřeba, že kód sám o sobě je dokumentace. K tomu můžu říci jen jedno - to je naprostá blbost.
Stačí nepracovat s vlastním kódem několik týdnů a už člověk ztrácí přehled o jemných detailech algoritmů, které sám psal. Nemluvě pak o tom, když je potřeba opravit chybu v rok staré aplikaci a nebo pracovat v kódu svých kolegů.
Také jsem slyšel "Jsem orientovaný na výkon a psaní komentářů mě brzdí". To je hodně krátkozraké, protože možná je člověk o pár minut rychlejší, když implementuje algoritmus, ale z dlouhodobějšího pohledu je to samozřejmě krátkozraké - čas strávený nad zjišťováním, jak jsem to já nebo můj kolega vlastně tehdy mysleli, je mnohem větší než kolik se dá ušetřit na jednom algoritmu bez komentářů. Ale já bych se vůbec do těchto polemik nepouštěl, protože dle mého názoru zdrojový kód se automaticky rovná kód plus komentáře.
Při psaní komentářů je potřeba nezapomínat, že zdrojové kódy nejsou Java soubory, ale také třeba konfigurační soubory, soubory prezentační vrstvy atd. To jsou také zdrojáky a ty je potřeba také komentovat.
Opačný extrém je takový, že na jeden řádek kódu připadají dva řádky komentáře. Není potřeba komentovat to, co je zřejmé z vlastního kódu. Zdrojový kód je jako dobrodružná knížka, kde jazyk Java popisuje vlastní děj příběhu. Komentáře jsou pak dějová vysvětlení, aby se čtenář v jednotlivých zápletkách neztratil. Pokud je toho vysvětlování příliš na úkor vlastního děje, tak pak to asi moc záživná knížka nebude.
Facilitace je klíč úspěchu
před 2 týdny
Příspěvky
16 komentářů:
S tim se neda nesouhlasit ;)
Na druhou stranu, komentare sebou prinaseji vetsi spravu nad projektem, ve kterem se delaji caste zmeny.
Otazkou pak je, kdy danou dokumentaci psat. Jelikoz neni mozne komentar refaktorovat stejne jednoduse jako java kod.
Ja jsem se v komentarich omezil na komentovani domain modelu, interface nad implementaci business logiky a ruznych util trid.
Vetsinou popisi metodu a casto pridam nejaky ten @see na objekt, ktery je dane metode zavisly.
Samorejmosti je komentar obsahujici co metoda dela, nikoli jen to, co je vysledkem.
Jen to refaktorovani, to je problem :(
Nesouhlasim.
Dokumentovat ano, komentovat ne. JavaDoc je nutnou soucasti kodu, rika co metoda dela. Jak to ta metoda dela maji popisovat testy. Aneb jak se rika v refaktoringove bibli komentar uvnitr metody je jasnym znamenim k refaktoringu.
Programator ma mit rozum a uvazit, co je vhodne a kde. Kdyz vyhrava lenost, znamena to, ze se mam zamyslet jeste jednou.
To plati i o komentarich, nejen o reseni.
Ja mel za to, ze testy slouzi jednak k testovani :) Ale take k ukazce pouziti kodu, coz s danym komentarem sice souvisi, ale neobsahuje vzdy to, co metoda dela.
Navic pri psani kodu a pouzivani knihoven tretich stran, asi tezko pokazde polezu do jejich testu, abych vedel co metoda dela.
Podle me, kratky popis o tom, co je uvnitr metody za magii by mel byt v komentari.
Vidím, že si budu muset dávat větší pozor na terminologii :). Sice jsem často psal o komentování kódu, ale myslel jsem vlastně dokumentování a komentování dohromady - prostě textové poznámky jak na úrovni tříd, metod, tak na úrovni vnitřních implementací vlastního kódu.
Pokud je metoda nebo třída určena k překrytí, pak je nezbytné v popisu metody napsat způsob implementace a informace o možnostech rozšíření.
Podla mna je najvhodnejsia kombinacia. V metode kde mam napisany nejaky zlozitejsi algoritmus je dobre napisat aj komentar ale napr pre gettre a settre, premenne, ci podobne objekty je to podla mna uplne zbytocne, kedze nazov je samovysvetlujuci.
Nelze než souhlasit. Jeden z názorů, které já propaguji je, že komplexní developer by měl umět psát všemi deseti, je to sice podružné pro výsledný kód, ale mně to značně urychluje práci právě např. při psaní komentářů..
to ze programator pise vsemi deseti se snad povazuje za standard ne? To je jako kdyby ridic neumel neumel otacet volantem.
Zvláštní, napadlo mě podobné přirovnání s řidičem.. ovšem volant není ta správná analogie. Bez otáčení volantem nedojede kam chce... Ale každý řidič profík si jistě umí vyměnit kolo, zejména protože je to násobně rychlejší než pokaždé spoléhat na žluté anděly.
Abych se vrátil k původní diskuzi, bohužel se stále setkávám s názory, že to potřeba není a že existuje spousta podpůrných nástrojů (např. code completion...). Ano, z jedné strany určitě ano, ale jsou to právě takoví spoléhači, kdo jako první neokomentují svou harakiri kličku v kódu, protože jim to prostě trvá dlouho a budou volat hesla "kod je sebevysvětlující" Není!!! A nikdy nebude.. Břídilů je na světě hromada.
Takový malý test, zkuste si dvěma prsty nadatlovat řádek komentáře "toto je komentář, který vkládám abych se ujistil, že psaní všemi deseti je přece jen pro programátora výhoda" Mně to zabralo 17 vteřin, kolik vám?
Tohle téma je víc než cokoli jiného zárodek flamewar :-) Kdysi jsem četl poměrně obsáhlý článek, který vlastně tvrdil, že množství a styl komentářů (a zdrojového textu samotného!) ukazuje na "vyspělost" programátora. Asi takto: nováček nemá problém k volání readLine() napsat komentář "načte řádku ze souboru", což je ve výsledku značně kontraproduktivní.
Osobně se snažím komentovat, přesně jak už tu někdo napsal, rozhraní, doménové objekty, utility, a samozřejmě "chytré obraty" (a ošklivé obraty) v implementaci. Za zcela zásadní považuju popisné identifikátory, např. nikdy nepoužívám takové jako "tmp", "buf" a podobně (s jedinou výjimkou, a to jsou písmena i, j, k jako indexy v cyklu, když nejde použít foreach). Mimochodem praktika rozdělování dlouhých metod na spoustu kratších je skvělým způsobem, jak z některých komentářů udělat identifikátory.
Urcite suhlasim, ze komentovat je dolezite. Ci uz kvoli prehladnosti pre seba aj pre inych.
Sice v praci nepouzivam javu ale ABAP ale moj konzultant si velmi pochvaluje komentovanie kodu - aj on sam - neprogramator (alebo skor velmi slaby programator) sa pomocou komentarov vie pomerne dobre orientovat v kode a pri nejakych chybach (chybach v implementacii procesov nie syntaktickych a semantickych) si skor porozumieme, pretoze ma v komentaroch popis vykonavaneho kodu
Takze komentovat jednoznacne ANO
podobne je to s odsadzovanim kodu, mennymi konvenciami a konvenciami zapuzdrenia - proste programatorska stabna kultura
Dokumentovat, nekomentovat. V praxi se nesetkavam s algoritmy, ktere by byly natolik chytre, aby si vyzadali komentar uvnitr kodu. On totiz spise rozbiji a zneprehlednuje.
Pri dobre volbe jmen, udrzovani kratkych metod a dokumentaci metod, nejsou komentare uvnitr kodu zapotrebi. Neni totiz lepsiho jazyku na popis algoritmu nez programovaci jazyk.
Jak tvrdi i chytre knihy, kde je komentar je potreba refaktoring metodu rozdelit na dve.
Btw. moje metody nemivaji vice nez 15 radku.
Taky souhlasim. Jeste bych dodal, ze prvnim komentarem kodu je dobre a vystizne pojmenovani promennych a clenu obecne. Z tohoto pohledu lze IMHO ospravedlnit, kdyz se o kodu rekne, ze je samovysvetlujici. Tim ale nechci rikat, ze je javadoc zbytecny.
> to ze programator pise vsemi
> deseti se snad povazuje za
> standard ne? To je jako kdyby
> ridic neumel neumel otacet
> volantem.
Aha, ja myslel ze to je potreba spis pro sekretarku, nebo zapisovatelku na soude :)
Za standard spis povazoval ze vic premysli nez pise a dodrzuje alespon elementarni pravidla prehlednosti kodu. Znam vic spatnych programatoru co pisou rychle deseti prsty, nez dobrych :)
Ja teda nepisu vsemi deseti, ale zvladl jsem ten komentar napsat za 15 vterin;) Ono to asi neni o tom umet psat vsemi deseti jako o tom umet na te klavesnici psat (nejlepe bez divani se na ni;)
u hmatové metody není efektivita v rychlosti generování znaků za minutu, ale že se programátor nemusí dívat ani na klávesnici ani do monitoru, v přesnosti a že píše rychle jak přemýšlí, aniž by si uvědomoval na kterou klávesu mačká - stejně jako, když mluví tak si neuvědomuje jak hýbá jazykem
Okomentovat