tifyty

pure Java, what else ?

Commenting is evil

Mi a fontosabb: a kommentezés vagy a unit teszt?

Hülye kérdése, mert mind a kettő fontos, és az egyik nem helyettesíti a másikat. (Pedig mindig azt szoktam mondani, hogy hülye kérdés nincs, csak hülye válasz.) A unit tesztekről már beszélgettünk a múltkor, most beszélgessünk a dokumentációról, és azon belül is a kommentekről.

Java programokban általában javadoc-ot írunk. Ez a dokumentáció részévé válik és azt kell leírni a dokumentált egységről, hogy azt a program más részeiből hogyan kell használni. Mi az amit csinál, milyen paramétereket kell átadni a metódusnak, milyen metódusok vannak az osztályban, milyen osztályok vannak a csomagban, mi a visszatérési érték stb. Dokumentálunk így csomagot, osztályt, metódust, változót (kihagytam valamit?).

A javadoc-nak nem feladata, hogy azt írjuk le, hogy hogyan működik a program. Arra ott van a kód, meg a kódsorok közötti dokumentáció. Vagy nem?

Annak idején (nem írok évszámot, mert nem emlékszem pontosan, meg mert rám szóltak, hogy 198-cal kezdődő évszámot írni ilyen szövegkörnyezetben nagyképűségnek tűnik, pedig nem az, csak kor) …

Szóval annak idején Pongor tanár úr írt egy olyan PASCAL programot, ami ellenőrizte, hogy a beadott, szintén PASCAL házi feladatok legalább fele komment sor legyen. És akkor ez volt a követelmény, és nagyon meg is felelt a világképemnek.

Az első ennek ellentmondó pofon pár éve volt, amikor az Atlassian JIRA forráskódját néztem. Semmi komment. Javadoc sem. Iszonyat mennyiségű (gondoltam akkor), normális mennyiségű (gondolom ma) unit teszt, de komment semmi. A következő pofon a soapUI forráskódja volt, amelyik szintén hasonló. Mind a kettő évek óta fejlesztett sikeres termékek. Akkor pedig ez így jó. A puding próbája, hogy megeszik.

Azután egyszer csak elém került Martin Fowler cikke. Aztán teltek az évek, és megbarátkoztam a dologgal. Az persze egyből lejött, hogy hát persze, hogy igaza van, de nem olyan egyszerű átformálni az embernek a világképét. És jöttek más tapasztalatok is, amik egyre jobban elhitették velem, hogy a kódsorok közötti komment, ami leírja, hogy hogyan működik a kód az maga az ördög.

A kód legyen olyan tiszta, világos és szép, hogy elolvasva látni lehessen, hogy mit csinál. Ha kommentet akarsz írni egy kód belsejébe, ami azt magyarázza, hogy hogyan működik, akkor az a kód túl bonyolult: re kell faktorálni, szétdarabolni, leegyszerűsíteni, más változó és metódus neveket használni satöbbi. Ha kommentet írsz a kódba az lehet rosszabb, mint ha nincs ott semmi. Mert aki meg akarja érteni, hogy hogyan működik a kód, a kommentet fogja elolvasni. És ha a program nem működ, hanem igazi, akkor a debugger szeme átsiklik a hibán, mert nem a kódot nézi, hanem a kommentet.

Ennek legdurvább esete egy ilyen kód volt:

// this variable is true to ensure 
// that the connection is tested well
final boolean testConnection=false;

Fél napomba került, mire megláttam, hogy false van oda írva.

Ezért elfogadtam, hogy nem írunk magyarázó kommentet a kódba. Ehelyett egyre tisztább kódot írok. De azt, hogy a soapUI vagy a JIRA forráshoz hasonlóan javadoc se legyen, azt nem tudtam megemészteni.

16 responses to “Commenting is evil

  1. tvik október 31, 2012 2:15 du.

    Éppen nemrég írogattam a témában: http://kodzaj.blog.hu/2012/07/26/komment_697

    Kis fejtegetés: oké, ne legyenek inline kommentek, csak beszédes változó/metódus/… nevek. Viszont a beszédes nevek is ugyanúgy félrevezetővé válhatnak egy idő után mint a kommentek.

    Ez a ne kommentezzünk mozgalom nekem olyan mintha a farok csóválná a kutyát. Oké, ne kommentezzünk, ha tényleg tiszta a kód. De a rossz kód nem lesz jobb attól hogy nincs felkommentezve.

  2. xabo október 31, 2012 3:41 du.

    Tetszik ez a bejegyzésed is, Péter. Mostanában “szembe jöttek” kódok és meglepve tapasztaltam hasonlót – hogy nem nagyon van comment “at all”. Én nem programozok, de ami keveset láttam, az alapján igazad van. Szia K.Szabó Zoltán

  3. gyz október 31, 2012 6:40 du.

    Javaslom: Robert C.Martin: Tiszta kód, Prentice Hall, itthon Kiskapu Igen, paradigma váltás kell ahhoz, hogy .vérünkké váljon amit ír. Idézi B.W Kernighan-t: “Ne kommentáljuk a rossz kódot- inkább írjuk át.”. A könyv egy egész fejezetet szentel a megjegyzéseknek, 26 oldalt, Szó van benne a TODO-ról a Javadoc-ról, Javaslom. A könyvet. Amely ugyancsak nem javasolja a kommentet. Óriási élmény a könyvben lévő némelyik kód megértése és tele van kódokkal, következetesen, mert kommentek nélkülivel. Talán nemcsak nekem élmény, hanem Java-ban igazán járatosak számára is. A Turbo Pascal 2.x-es programjaink valóban teli voltak megjegyzéssel, de ott például még a 80-90-es évek codebook-jainak tipusfüggő változóneveit illett használnunk. Tetszik a bejegyzés.

  4. Simon Bence október 31, 2012 11:21 du.

    Valahol (ha jól emlékszek pont Fowler-nél, de most nem tudom felidézni, melyik írásában) azt olvastam, hogy tulajdonképpen két fajta célzattal kerülhet komment egy kódba:
    Az első fajtája a javadoc. Ennek célja ugye, hogy a kód felhasználójának adjon tömör leírást. Hogy miért fontos ez? Ha például egy más által hívott metódust hívunk, legyen az egy frameworkben, vagy a projekt egy távolabbi részében, nem feltétlen szeretnénk állandóan a forrást kutatni. Persze jó, ha képünk van róla, de ez szimpla produktivitás: ha a fejlesztő egyszer odaírja, akkor az lényegesen kevesebb időráfordítás, mint mindannyiszor áttekerni oda. Főképp igaz ez a modern IDE-kre, amelyek leginkább előbbit támogattják: a kódkiegészítés is a javadoc-ot jeleníti meg, nem a kódot. Persze ennek nem kell eposznak lennie, viszont szerintem mindenféleképpen tartalmaznia kell a “speciális eseteket”: null-al tér vissza, ha ez, vagy az. Hogy ne lepődjünk meg.
    A másik helyzet az inline comment. Na ez már trükkösebb: igazából ezeket hivatalból üldözni kéne. Ezek szolgálnak arra, hogy a komplex, nem jól komponált kódrészleteket magyarázzák. A kód helyett. Szóval e tekintetben valóban a komment eliminálása lenne a cél, de az élet ennél kevésbé egyértelmű: sajnos lesz olyan kódrészlet, ami -nem feltétlenül technikai, de mondjuk üzleti okokból- eléri azt a bonyolultságot, amikor szükséges egy megjegyzés. Persze riktán és indokoltan.
    Ez az a “szemléletet” (mondom, talán valamikori Fowler írás, de próbálok utána gonolni még), amit magamévá vettem, és számomra ez egy ideális egyensúlyban tartja a lustaságot és a pluszban karban tartandó karakterek számát.

  5. Simon Bence október 31, 2012 11:41 du.

    Elképzelhető, viszont közben utánagondolva biztos vagyok benne, hogy valamilyen formában a Clean Code, vagy a Clean Coder-ben volt (Szóval Robert C. Martin).

  6. Tamás november 2, 2012 8:12 du.

    Az inline kommenteket eddig 1 dologra tartottam megfelelőnek: ezzel üzenek annak, aki review-zza a kódomat, amikor olyan megoldást választok, amit ő nem választana.

  7. S.E. november 5, 2012 1:14 du.

    Nem olvastam még el a hivatkozott könyveket, de szerintem ez is egy a szélsőséges álláspontok közül. Nem hiszem, hogy néhány odaírt szó vagy mondat ártana a kódnak – különösen, ha egy hosszabb darabról van szó. Ugyanakkor persze az is zavaró, ha keresni kell a kódot a sok komment között.

    Szóval szerintem ésszel, mértékkel nyugodtan lehet kommentezni. Valahol középúton van az igazság…

    • Janos Haber november 14, 2012 3:49 du.

      Szerintem eloszor olvasd el a konyveket (Tiszta Kod cimut ajanlom en is). Igazabol a commentek megzavarjak azt aki a kod olvasasahoz szokott. Olyan emberekrol beszelunk akik egesznap a kodot nezik, igy azt konyebben olvassak, nem jo kizokkenteni oket egy commentel.

  8. Kofa november 7, 2012 10:54 de.

    Nekem ez az kedvenc kommentálós cikkem:
    http://www.stickyminds.com//testandevaluation.asp?Function=edetail&ObjectType=ART&ObjectId=9041&tth=DYN&tt=siteemail&iDyn=3

    Szerintem van értelme az in-line commentnek, nem azért, hogy kusza, rossz kódokat elmagyarázzon, hanem hogy elmondja, miért született egy nem triviális döntés (Tamás review-ra vonatkozó megjegyzése ennek speciális esete), vagy miért annyi egy konstans értéke, amennyi (elég egy rövid hivatkozás a specifikáció megfelelő pontjára).

    Comments themselves are a sweet smell when they tell you why something was done. When you come across a comment while you’re reading code, it should stop you dead in your tracks. The programmer before you felt so compelled to tell you something important—something that couldn’t be documented anywhere else—that she left you a comment. Ignore it at your own peril.

  9. Máté november 24, 2012 8:29 du.

    Kofával értek én is egyet, illetve találkoztam még egy speciális esettel: amikor az ügyfél kért határozottan bizonyos megoldást, amiről tudtuk, hogy később ő maga fogja hibaként bejelenteni – a kódban minden ilyen helyen ott volt a hivatkozás az adott ticket-re, hogy később ne vegyük ki automatikusan a hack-et, mint valóban rossz megoldást.

    Akkor is hasznos, ha workaround kell a környezet/VM/külső interface hibája miatt.

  10. Janos Haber december 5, 2012 2:12 du.

    Ezzel csak felig ertek egyet.

    A code review-ra peldaul ott a hibakezelo rendszer, tessenek oda irni ha valami uzenet van (ugy is azon keresztul kuldod code review-ra a kodot nem?).
    Az ugyfel kereseit is azon keresztul fogod kapni es jo esetben ossze van kotve a verzio kezelo rendszerrel a hibakezelo rendszered, igy ismet semmi keresnivaloja a kodban. Ha peddig valaki automatikusan eltavolit egy kodot (???) azt ott helyben kell pofancsapni egy peklapattal, eloszor nezze meg mikor kerult bele a kod (annotations, + logikusan nalunk kotelezo a hibajegy megadasa a commentben), akkor megtudja nezni hogy miert kerult bele. Gondolom most mindenki azzal jon hogy tul sok ido, miert nem eleg csak odairni. Azert mert szetdarabolja a kodot. Lehet nem azonnal, lehet csak 3-4-10 verzioval kesobb, de szetfogja darabolni.

    • v december 5, 2012 2:18 du.

      Az ügyfél használja a programot, és nem fejlesztet bele semmit két évig. Aztán elő kell mégis venni, és ráállítani egy teljesen új csapatot. Esetleg (jogszerűen) akár egy másik fejlesztő cég kapja meg a kódot, hogy ezt fejlesszétek tovább.

      Hol van akkor a hibajegy, a code-review tool? Hol vannak a comittok, merge-ek és rebase-ek, és a commit message-k?

      A realitás, hogy ilyenkor nem marad más, mint a péklapát. De nem egymást pofon csapdosni, mert az nem jó semmire, hanem lapátolni a lapra áttolni valót.

      • Janos Haber december 6, 2012 10:12 de.

        1. Erre valo a dokumantacio, ahol rogzithetok az ugyfel altal kert nem trivialis illetve hibas megoldasok
        2. A code review-nak semmi koze ehhez az a fejlesztes resze es semmi koze annak hozza aki atveszi.
        3. Ha a te esetedbol indulunk ki akkor majdnem mindenhova ahol uzleti logika van irhatnank egy commentet.

        Szerintem az nem megoldas hogy commenteket irunk a kodba. Ha masik csapat veszi at igenis ismerje meg a kodot magat, ha valami peddig ugyfel kerese volt az le lesz irva dokumentacioban (amugy le kellene irni hogy legyen mire hivatkozni ha esetleg kesobb meggondolja magat). Egyetlen kivetel szerintem “ha workaround kell a környezet/VM/külső interface hibája miatt” es ez valamiert nem fe bele a dokumentacioba.

  11. v december 6, 2012 10:57 de.

    Én ezt általánosan úgy fogalmaznám meg, hogy abban az esetben van helye a kódban a kommentnek, ha olyan információt akarunk rögzíteni, amelyik az egységbezárás megsértéséből adódik.

    Ha nincs semmilyen szinten megsértve az egységbezárás, akkor a kód olvasható. Ha a kód egy megoldása olyan, ami valamilyen külső ok miatt lett olyan, akkor ez by definition az egységbezárás megsértése. Néha elkerülhetetlen. Például környezeti hibák, működés kezelése.

    De semmiképpen nem gondolom azt, hogy ahol üzleti logika van, oda komment kell. Oda, és olyan komment kell, amelyik szükséges és segíti a jövőbeli fejlesztőt, és amelyik információ a jövőbeli fejlesztő számára máshonnan nem érhető el.

    Ki, kivel, mikor, hol, mit csinált: az iskolai papír hatjogatós gyerekjáték, és nem kell a továbbfejlesztéshez, amikor már egy másik csapat fejleszt. Mi a jó abban, hogy tudom, hogy jo12zsi írt egy bizonyos kódot. Ha ugyanaz a csapat fejleszt, akkor jó lehet a Józsit megkérdezni, de olyankor ott van a VCS is.

    //TODO valószínűleg hasznos. Megoldható másképp is, de talán ez a legegyszerűbb, és IDE is támogatja.

Vélemény, hozzászólás?

Adatok megadása vagy bejelentkezés valamelyik ikonnal:

WordPress.com Logo

Hozzászólhat a WordPress.com felhasználói fiók használatával. Kilépés / Módosítás )

Twitter kép

Hozzászólhat a Twitter felhasználói fiók használatával. Kilépés / Módosítás )

Facebook kép

Hozzászólhat a Facebook felhasználói fiók használatával. Kilépés / Módosítás )

Google+ kép

Hozzászólhat a Google+ felhasználói fiók használatával. Kilépés / Módosítás )

Kapcsolódás: %s

%d blogger ezt kedveli: