Éppen a Clean Code kommentekről szóló fejezetét olvasom Robert C Martin-tól és azt kell hogy mondjam, nem értek vele 100%-osan egyet. Az ő véleménye szerint a kommentek nagy része szükségszerűen rossz, valami olyasmit fejez ki, amit a programozó nem tudott beleépíteni a kódba. Egyfajta magyarázkodások, amik ráadasul időnként elavulttá válhatnak, mert a kód fejlődik, de a kommentet senki sem frissíti.

Egy programozónak elég könnyű magáévá tenni ezt a véleményt, és párszor már vissza is hallottam. Nem kommentelünk, mert Uncle Bob Martin szerint nem kell. Hurrááá, úgyis utálunk kommentelni! Inkább használjunk beszédes változó és metódusneveket, írjunk tiszta kódot! Nemes elhatározás.

A probléma ott kezdődik, hogy sokan elfelejtik a fejezet azon részét, ami a valóban hasznos kommentekről szól, amiket érdemes, sőt ajánlott alkalmazni. Nem is annyira extrém eset, amikor már a publikus metódusokról is lemaradnak a javadoc-ok. A szerző egyébként nagy híve a Test Driven Development-nek. A fejezetben nincs explicite kiemelve, de a tiszta kódhoz hozzá tartoznának a unit tesztek is, amik egyfajta dokumentációként szolgálnak. Általában végül mégsem sikerül tiszta kódot írni, nincs unit teszt, a beszédes változó- vagy metódunevek pedig szintén elavulttá, félrevezetővé válnak. A metódus már nem azt csinálja, ami a (beszédes) neve. Esetleg hibásan működik. De ha nincs komment honnan tudjuk hogy mi a hibás és mi az elvárt működés? Általában tippelünk, ami néha nagyon nem jön be. Köztudott, hogy a számítógép nem azt csinálja amit szeretnénk, hanem amit beleprogramoznak. Kommentben legalább le lehet írni hogy mit szeretnénk.

A javadoc komment arra is jó, hogy leteszteljük, meg tudjuk-e fogalmazni egyszerűen, mit csinál egy osztály vagy egy metódus. Ha tényleg magyarázkodni kell a kommentben és kisregényt kell írni, akkor baj van a kóddal, a kitalált koncepcióval. Interfész metódusoknál más a helyzet, ott ki kell bontani a lehetséges implementációs részleteket rendesen.

Egy jól összerakott javadoc komment tapasztalataim szerint elriasztja a munkatársakat -és néha saját magamat is- a meggondolatlan átalakításoktól. Ha valami jól fel van kommentelve, az valószínűleg jól ki lett találva, tiszteletet parancsol. Nem biztos hogy bele kellene nyúlni, de ha belenyúlok át kell írni a javadoc-ot is, át kell gondolni mit is akarok csinálni.

Az nagyon jó dolog, ha a kód jól olvasható és érthető, de 15 év programozás után az emberi nyelvet még mindig gyorsabban olvasom mint a programkódot. Az emberi nyelv elég jól kifejlődött pár ezer vagy millió év alatt. Épp ma történt, hogy 4 percembe telt, mire némi klikkelgetés és kódböngészés után kiderítettem hogy egy sablonfeldolgozó metódus milyen speciális karaktereket használ a változók behelyettesítéséhez. Ha lett volna komment (amit 1 perc megírni), akkor másodpercek alatt elolvastam volna. Nem az a kvázi 3 perc különbség számít, hanem hogy ugyanezt a metódust sokan használják és nekik is ugyanennyi plusz meló a működés értelmezése. Sok kicsi sokra megy, órák, sőt napok is összejöhetnek ilyenekből. Ráadásul az állandó kódértelmezés folyamatosan kontextusváltást igényel. Szeretem más kódját böngészni és értelmezni, de amikor már 10 osztállyal arrébb járok néha azt sem tudom hogy mit akarok valójában. Ilyenkor vissza kell kapcsolni egy fokozatot. Elő a papírt ceruzát és osztálydiagramokat kezdek rajzolgatni. Mennyi idő megy el ezzel? Sok.

A tiszta kód egy idealista dolog. A szoftver soha nincs készen. A végtelenségig lehetne reszelgetni a program részeit, hogy tökéletes legyen, de időnként le kell tenni a tollat, be kell commit-olni a részeredményt a verziókezelő rendszerbe. Mellesleg ajánlott minél gyakrabban. Megesik hogy maradnak benn nem túl jól kidolgozott részek. Olyan is megesik, hogy a fejlesztés közben már látszik a lehetséges irányváltás. Pl. látszik hogy az osztály többfelé fog osztódni. Ilyenkor én nem átallok kommentekből szekciókat képezni és oda gyűjtöm az osztályon belül azokat a tagokat, amik valószínűleg le fognak válni egy másik osztályba. Ez Martin bácsi szerint nagyon rossz gyakorlat, nekem mindenesetre rengeteget segített eddig.

Végül a kommentezés (főleg ha színes IDE-vel dolgozunk) széttagolja a kódot, segít a tájékozódásban.
És időnként még vicces is.

Te rendesen kommentezel?