spájame
slovenskú
IT komunitu
pridaj sa
Registrácia · Login

Peter Špireng 7.6.2012
Hodnoť článok:
0 1

Lepší kód alebo prečo komentár môže kódu škodiť

Zdá sa, že v programátorskom svete existuje jedna konštantná pravda: Komentuj svoj kód. Na prvý pohľad to vyzerá, že komentovanie je to najlepšie, čo môžem pre seba, spolupracovníkov a kód spraviť. Samozrejme, ak si mám vybrať medzi kódom a kódom s komentárom, beriem to druhé. Je to ale to jediné a najlepšie riešenie? Alebo existuje ešte niečo lepšie, ako písanie komentárov? Nejaký lepší kód?

Poďme sa na začiatok trochu zamyslieť, o čom komentovanie je. Hlavným účelom komentárov je (ako už napovedá názov) komentovať. To znamená informovať o tom, čo kód vykonáva. Vysvetľovať príkazy kódu. A to by mohla byť vážne užitočná vec. Ale to len v tom prípade, že by som prijal fakt, že kód, ktorý treba komentovať, je v poriadku. A teda v poriadku je aj samotné komentovanie. Z čias assemblera sme sa už pohli niekde inde a dnes sa pomerne veľa programov tvorí vo vyššom programovacom jazyku. Na vyšších programovacích jazykoch je pekné to, že sú krokom smerom od stroja k človeku. Okrem toho, že sú minimálne čitateľnejšie sami o sebe, majú aj väčšiu plastickosť (alebo ešte krajšie slovo je „tvárnosť“), čo im umožňuje presnejšie popísať problém, ktorý kód rieši (modelovať doménu). Schopnosť vytvoriť si sadu tried s metódami a premennými, ktoré si viete podľa ľubovôle pomenovať, otvára možnosti v tom, ako bude vyzerať vnútorný svet vášho programu. Inak povedané, môžete ho napísať dobre. A ak ho napíšete dobre, nemusíte ho vysvetľovať.

To, k čomu mierim, je fakt, že komentáre môžu byť často hrubou záplatou na zle napísaný kód. Príkladom (možno trochu extrémnym) môže byť zadefinovanie premennej:

// distance from left margine
int x;

A teraz to skúsime trochu upraviť:

int distanceFromLeftMargine;

Obidva tieto zápisy obsahujú rovnaké množstvo informácií a sú si prakticky rovnocenné. Rozdiel sa začne prejavovať až pri používaní tejto premennej niekde v kóde. V prvom prípade si musíte pri čítaní kódu v hlave automaticky budovať prekladový slovník (... “Čo bolo to x?“ ... (chvíľka zamyslenia)... “Aha, vzdialenosť od ľavého okraja. Poďme ďalej ...“). Takto vyzbrojený informáciami, ktoré sú v komentároch postupne dekódujete kód. V tom druhom žiadne dekódovanie nie je potrebné. Informáciu o tom, čo je to za premennú, máte všade tam, kde ju použijete. Podobne môžete pristupovať ku názvom všetkých objektov v programe. Dobré pomenovanie je dôležité a komentáre sa mu bohužiaľ umožňujú vyhnúť. Nemusíte predsa dobre pomenovávať kód, ak ste ho okomentovali. Podobný problém je s komplikovaným kódom. Algoritmus sa dá napísať rôzne. Aj tak, že ho bude mať problém pochopiť ktokoľvek iný okrem vás. Ale aj zle napísaný kód vie prejsť cez kontrolu, ak má komentár. V prípade, že ak by som aj prijal takýto spôsob tvorby kódu, je s komentármi ešte jeden problém.

Komentáre predstavujú dokumentáciu kódu. Je to síce taká dokumentácia distribuovaná v kóde, ale stále je to dokumentácia, ktorá popisuje kód. Akákoľvek systémová dokumentácia má jeden spoločný problém a to je, že duplikuje popis riešenia voči kódu (duplicita popisu spočíva v tom, že kód sám už riešenie popisuje). A duplicita nie je dobrá, pretože so sebou prináša aktualizáciu. V našom prípade to znamená, že čím viac máte komentárov, tým skôr sa rozíde informačný obsah v komentároch s tým, čo kód robí. Ak už ste niekedy zažili schizofrenický pohľad na kód s komentárom, kde komentár hovoril jedno a kód robil zjavne niečo iné, tak viete o čom hovorím. Ono to stále nakoniec vyhrá kód, lebo ten má vždy pravdu ale divný pocit, či ten kód chápem správne a či naozaj predsa len nejako nerobí to, o čom hovorí komentár tam určite chvíľu je.

Aby to nevyzeralo, že komentár je najväčšie zlo na svete, tak existujú legitímne prípady, kedy sa dá použiť. Napríklad, ak začínate písať funkciu písaním pseudokódu medzi riadky, do ktorého potom dopisujete normálny kód. Alebo keď kód odpovedá na najzákernejšiu otázku zo všetkých: Prečo? (viac o jej zákernosti inde). Preto netvrdím, že sa pri pohľade na komentár treba automaticky prežehnať a očakávať najhoršie. Tvrdím len, že komentár sa môže stať lacnou náhradou za dobre napísaný kód. A pritom to ani zďaleka nie je to isté...

Čo teda robiť namiesto komentovania? Písať lepší kód. Vždy ak máte pocit, že by si nejaký kód zaslúžil komentár, je možno namieste sa zamyslieť, či sa nedá napísať tak, aby komentár nevyžadoval. Ja viem, že to nie je jednoduché, a že je to práca naviac, ale to je akákoľvek práca aj v inom odbore, ktorá má mať určitú kvalitu. Ak by som dal stolárovi vyrobiť stôl a on by mi doniesol hotový kus, ale namiesto opracovania hornej dosky by na ňu nabil kus gumy so slovami, že to v podstate plní účel, tiež by som nebol nadšený. Rovnaké je prehrabávať sa komplikovaným kódom, lúštiť komentáre a zamýšľať sa nad ich aktuálnosťou. Program funguje, plní svoj účel, ale kvalita práce je diskutabilná.

A na záver: V súčasnosti mi nie je známy žiadny programovací jazyk, ktorý by nemal funkčnosť komentárov. Iste by bolo zaujímavé vidieť nejaký stredne veľký projekt napísaný v takomto jazyku. Buď by bol ten kód dobrý, alebo by sa z programátorského oddelenia ozývalo značne veľa nadávok.

Peter Špireng Peter Špireng

"We are all in the gutter, but some of us are looking at the stars." -Oscar Wilde


Hodnoť článok:
0 1

15 komentárov k článku:

Komentovať môžu iba prihlásení

Zaregistruj sa cez bezplatnú registráciu alebo použi login cez Facebook (FB Connect)

Prihlás sa tu, ak už máš profil na Zajtra.sk:


Zabudol som heslo

0 0 FrewCen 6.7.2012 09:12:50
Vieš ako cyklov tam mám dosť. Veľmi.... Index pre jeden, a čo pre druhý? K tomu, transakcie je názov kolekcie : IEnumerable takže tento názov nemôžem použiť.
0 0 Peter Špireng 6.7.2012 08:11:07
@FrewCen: V tomto jednom prípade by som zvolil pre premennú s indexom nazval len "index". Ak sa pozrieš na riadok

for(int index = 0;index < zoznamTransakcii.Length;index++)

a riadok

zoznamTransakcii[index] = new Transakcia();

tak by z názvu poľa "zoznamTransakcii" malo vyplývať, že index je indexom v zozname transakcii (osobitne by som zvážil, či "zoznamTransakcii" by nemal byť premenovaný ako "transakcie"). V každom prípade mi vychádza že komentár pre premennú "index" nie je potrebný, lebo minimálne v tomto prípade je jej použitie na každom riadku (aspoň pre mňa) pomerne jasné.
Ako som písal nižšie, teória a praktiky pomenovania sa nedajú napísať do jedného komentára a ani článku. A ani to nebol účel môjho článku. Ním som chcel len povedať, že k okomentovanému kódu existuje aj iná alternatíva ...
0 0 FrewCen 5.7.2012 19:59:23
Osobne s týmto článkom veľmi nesúhlasím. Už len keď si pomyslím na premenné v cykle, ako ich používam.....

for(int indexZoznamuTransakcii = 0;indexZoznamuTransakcii < zoznamTransakcii.Length;indexZoznamuTransakcii++)
zoznamTransakcii[indexZoznamuTransakcii] = new Transakcia();

Si si istý že je to dobrý nápad? Ak tam nedám jedno písmenko s komentárom, tak sa z toho stane úplne neprehľadný kód.
0 0 Miloš 15.6.2012 17:54:08
Zvolil by som kompromis:
- JavaDoc alebo teda obdobu pre PHP
- dĺžka názvu niečo medzi, čiže tak cca do 8 znakov, ale nech viem, čo to robí
0 0 Ján Baláž 11.6.2012 17:21:44
Peter, zaujímavý pohľad na komentáre, ďakujem za inšpiráciu. Takisto oceňujem aj predošlé články a uvítam ďalšie, ak si nájdeš čas :)

Ďakujem.
0 0 Jozef Bakos 8.6.2012 12:25:32
No ja som programaor a bez komentov by som bol v riti. Napriklad ked pisem mulifunkcnu funkciu alebo proceduru. Tak bez komentov je to len hromada blabolu na kopu riadkov. Neznasam osobne kod v korom nie su komenty alebo ak su tak su take biedne napisane ze stale si myslite ze riesite tu istu vec ale pri tom se uplne inde. V linux kodoch je vela toho potom nic nerobim len nadavam.
0 0 Peter Špireng 8.6.2012 07:31:34
@Marek Sedlacek: Ťažko sa mi posudzuje keď nevidím zvyšok kódu, ale zvolil by som asi

accountProvider.getDataWithOwnerAndCardInformationById()

(chce to samozrejme dedikovanú triedu na prácu s účtami)
Tiež by som zvážil koľko detailov z vnútorného fungovania funkcie je potrebné zverejniť (buď na úrovni komentára, alebo popisu funkcie). Vynikajúce čítanie na túto tému sú knihy Čistý kód (ktorú už spomenul Peter Jurkovič nižšie) a Dokonalý kód. Tam sa dá nájsť veľa odpovedí, ktoré sa to do tohto komentára jednoducho nezmestia...
0 0 Peter Bočej 8.6.2012 07:22:49
Som zastancom len komentovania funkcii. Ak je niekde chaoticky kod (netvrdim ze nemoze byt), treba sa zamysliet nd refactoringom a rozhodit ho podla logiky do viacerych oddielov (funkcii) a tie okomentovat v popise.
Co sa tyka premennych tak: x: x-axis, y: y-axis, i: iterator, tmp: pomocna ... ostatne pomenovat tak, aby maly zmysel.
0 0 Jozef Chutka 7.6.2012 23:11:57
Myslim ze brainfuck ani white space nemaju komentare
0 0 Marek Sedlacek 7.6.2012 21:47:22
Drahy autor
Mozes mi vysvetlit, ako pomenovat metodu ktora vola daku sluzbu tak aby bolo jasne co ta sluzba vracia a co berie na vstupoch atd atd, bez toho aby bol jej nazov na 5 riadkov.

Alebo volajme len stupidny select v dakej metodke, ktora sa vola getDataForAccount(). Takze ty navrhujes getDataForAccountWithLoadedOwnerDataAndCardInformationByAccountId(). Totiz to ten select v skutocnosti robi.

@Andrej - compilator ich z kodu vyhodi a kompiluje cisty kod.
0 0 Michal Biroš 7.6.2012 21:39:16
Uplne najlepsie je uzatvarat magicky kod do nejakej metody (funkcie) a viac sa toho nedotykat. :D Uzatvaranie medzi komentare nepomaha.
0 0 Andrej Mihaliak 7.6.2012 21:34:00
neviem či sa nemýlim ale komentáre sa nekompilujú či?
0 0 Peter Jurkovič 7.6.2012 20:58:46
Odporúčam prečítať knihu "Čistý kód", veľmi dobrá kniha (nie len pre Java programatorov).
0 0 František "yderf" Haško 7.6.2012 20:53:32
Mam uplne necakanu poznamku: najlepsie je pisat dobry kod a komentovat ;-)
0 0 Neo 7.6.2012 19:29:29
Moja rec. Tiez nekomentuje kod skoro vobec, pisem ho tak aby bolo na prvy pohlad jasne ze co je co a kto robi co.
Zajtra.sk > Život > Veda > Lepší kód alebo prečo komentár môže kódu škodiť


Kritika

Vieš ako robiť veci lepšie? Pomôž našim odvážnejším členom a skritizuj im projekty!

Reklama

Seriály zo Zajtra.sk

Reklama