HTML

asdf

Komment

2012.07.26. 23:12 tvk

É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?

3 komment

Címkék: komment antipattern

A bejegyzés trackback címe:

https://kodzaj.blog.hu/api/trackback/id/tr384680835

Kommentek:

A hozzászólások a vonatkozó jogszabályok  értelmében felhasználói tartalomnak minősülnek, értük a szolgáltatás technikai  üzemeltetője semmilyen felelősséget nem vállal, azokat nem ellenőrzi. Kifogás esetén forduljon a blog szerkesztőjéhez. Részletek a  Felhasználási feltételekben és az adatvédelmi tájékoztatóban.

Kozka 2012.07.27. 08:41:07

Nem olyan rossz dolog kommentezni. Neha felkommentezek egy elbaszott kodreszletet, amibol meg jobban latszik mennyire el van bonyolitva. A code-review soran rendszeresen visszadobjak ezeket a dolgaimat.

Sequoyah 2012.07.27. 09:32:43

Egy helyen érdemes szerintem kommentelni, algoritmusok belépési pontján, ami általában a publikus API. Szóval magát az algoritmust írom le pár szóban, a célját és az alap működését, nem a részleteit.
Az algoritmus le van bontva a CC szerint ezernyi rész-metódusra, a halálom amikor ezek is fel vannak kommentezve, megtörve, és olvashatatlanná téve a kódot.

tvk · http://kodzaj.blog.hu 2012.07.27. 11:40:57

@Sequoyah A privat metodusok kommentelese Uncle Bob szerint is antipattern. Az en elvem az, hogy ha egy privat metodushoz megiscsak tudok egy frappans, rovid, kontextusfuggetlen javadoc-ot irni, akkor az a metodus lehet hogy felhasznalhato mas helyen is, kesobb erdemes lehet kitenni egy kulon osztalyba public-ba.

Ugyanez fokozottan igaz privat nevtelen belso osztalyokra is.