Jak komentovat zdroják

V diskuzi k jednomu minulému článku týkajícího se chyb v diplomkách jsem dostal otázku: Jak se stavíte ke komentování diplomky? Díky za otázku a tady je odpověď.

Komentář zdrojového kódu je návod, který slouží komukoli, kdo chce:

• pochopit co program dělá, aby mohl později navázat (třeba jiný student)
• pochopit co program dělá, aby mohl zhodnotit, jestli autor ví co vlastně naprogramoval a proč (třeba oponent)
• pochopit co program dělá, aby mohl opravit chybu (třeba vy sami)

Jak jste si všimli, tak komentář slouží k vysvětlení kódu. Ale k tomu low-level. High-level vysvětlení by mělo být v textu diplomky (návrh tříd, atd.). V textu diplomky naopak neuvádějte velké kusy kódu. Kód má smysl, jen pokud se jedná o něco úžasného, na co jste opravdu hrdí a nikdo na světě to nenapsal lépe :). Popisovat implementaci standardních algoritmů nemá smysl.

Pokud chcete popsat algoritmus, je obvykle vhodné použít pseudokód. Je kratší, čitelnější a implementačně "nezávislý". Výjimkou mohou být funkcionální jazyky... ale tady se pouštím na tenký led :).

Takže komentujte tak, abyste vystihli podstatu kódu = jak a proč. Komentovat printf je fakt zbytečné. Používání různých doxygen a podobně je OK (a vhodné).

Z pohledu oponenta je hodnocení zdrojáků součástí posudku:

7. Realizační výstup
Zde se vyjádřete k úrovni a funkčnosti technického nebo programového řešení ve vztahu k dosaženým experimentálním výsledkům práce. Případně také zhodnoťte, zda software nebo zdrojové texty, které nevytvořil sám student, byly v práci použity v souladu s licenčními podmínkami a autorským právem.

Jak vidíte, nejsou dána žádná striktní pravidla, jak by měly vypadat komentáře. Hodnocení závisí čistě na oponentovi.

Na závěr jedno upozornění: nejen komentáře jsou důležité. Též byste měli dodržovat citační etiku (podobně jako v textu práce) a označit části kódu, které jste si "vypůjčili" od jinud - včetně licence, kterou nesmíte porušit! Co se týká hodnocení celého díla, tak k tomu někdy příště.