Kommentek a kódban

Sokat hallani másoktól, hogy írjunk kommentet a kódba. A fő érv a javaslók körében az, hogy ezáltal a programkódot érthetőbbé tehetjük. Az idők során megtanultam azonban azt, hogy a kommentek sok esetben nemhogy hasznosak, de kifejezetten károsak is tudnak lenni.

Milyen célból használunk kommentezést?

• programrészletek átmeneti kikommentezésére, mert valamit ki szeretnénk próbálni (nyomkövetés céljából),
• egy alternatív implementációt próbálunk létrehozni, és meghagyjuk az eredeti kódot,
• hogy elmagyarázzuk, éppen mit csinál egy kódrészlet (pl. osztály, metódus, metóduson belüli részkód), vagy mit jelentenek egyes programstruktúrák (pl. változók, mezők),
• hogy elmagyarázzuk, hogyan működik a kód, 
• hogy elmagyarázzuk, miért implementáltunk valamit úgy, ahogy,
• TODO-k.

Ottfelejtett kódrészletek

Ha egy kódrészletet újra akarunk írni, gyakran tesszük azt, hogy az eredeti kódrészletet kikommentezzük, és az alapján - mintegy emlékeztetőt használva - írjuk meg az új kódot. Az így ottfelejtett kódrészleteknek megvan az a veszélye, hogy a valódi kód olvasásakor, áttekintésekor állandóan ezt a kódot fogjuk kerülgetni, és ezáltal fókuszunkat vesztjük. Lehet, hogy az amúgy egy képernyőn elférő metódus sem látszik már, mert tele van tűzdelve mindenféle régi szeméttel. Vannak gyűjtögető életmódot folytató emberek, akik egyszerűen úgy gondolják, hogy "jó az, ha megvan". Valóban jó? Ha ott hagyunk egy kódrészletet, és helyette írunk egy másikat, fogjuk-e még hasznát venni az eredetinek? Csak egy kis időnek kell eltelnie, és már semmi haszna nem lesz, csak gátol minket az olvasásban.

Az otthagyott, kikommentezett kódnak megvan az a további veszélye is, hogy az arra tévelyedő fejlesztőtársaink elkezdik elemezni, értelmezni. Kérdéseket vet fel, kétségéket ébreszt bennük, elgondolkodtatja őket. Ez ritkán produktív. Ha meglátok egy ilyet, azonnal törlöm. (A source control-ban úgyis megvan.)

Mit csinál a kód?

Ha valaki elkezd a kódba egy kisregényt írni, hogy az adott rész épp mit csinál, az általában nem veszi a fáradtságot arra, hogy a kódot tisztességesen megírja. Miért? Ha a változóink, metódusaink, osztályaink elnevezése megfelelő ("beszédes"), akkor nem feltétlenül kell leírni azt, hogy mit csinál a kód. Például metódusaink elnevezésekor törekedni kell arra, hogy a metódus neve felfedje azt, hogy az mit csinál (nem tudom eléggé hangsúlyozni a mit szócskát). (Ha nem tudunk nevet adni neki, az alkalmasint azt jelenti, hogy épp rossz úton haladunk.)

Egy hosszú metóduson belül sem kell kommenteznünk az egyes részeket, mert ha azokat megfelelően emeljük ki külön metódusba, máris tudunk nekik külön nevet adni. (Refaktorálás: Extract Method).

API-k esetében kötelező a szabványos kommentezés (pl. legalább metódus szinten), ld. pl. Javadoc, vagy .NET XML comments.

Hogyan működik a kód?

Nem maga a kód írja le önmaga működését? Ha a kód jól struktúrált, és a metódusainknak, változóinknak tudunk értelmes(!) nevet adni, szükség van-e arra, hogy leírjuk hogyan működik a kód? Úgy gondolom, általában nincs rá szükség. 

Miért?

Ha azt szeretnénk fejlesztőtársainknak kommunikálni, hogy valamit miért éppen úgy valósítottunk meg ahogy, akkor azt kifejezetten hasznos kommentekben leírnunk. Kiváló példa erre a workaround-ok esete: valamilyen technológiát alkalmazunk, aminek van egy általunk ismert hibája. Hogy összességében elérjük a célunkat, ezt valahogyan körbe kell programoznunk, és a megoldás sokszor nem triviális. Ilyenkor teljesen természetes, hogy jelezzük, miért csináltunk meg valamit úgy, ahogy.

TODO-k

A TODO-k nagyon hasznosak. Ha valamit nem implementálunk teljesen, akkor oda írjuk a kódban a megfelelő helyre, hogy azt még meg kell csinálni (pl. TODO: A 24 számjegynél hosszabb hitelkártyaszámok kezelése). Minden modern fejlesztőkörnyezet képes a forráskódban elhelyezett TODO-k kigyűjtésére, és ezáltal ezekkel utólag is foglalkozhatunk.

A TODO-kkal csak egyetlen gond van: ha egy kicsit nem figyelünk, elszaporodnak, és csak kerülgetni fogjuk őket. Eleinte frusztrációt okoznak, de rövid időn belül immunissá válunk rájuk, és a TODO-k mögötti valódi problémák rejtve is maradnak. Tapasztalatom szerint a produkciós környezetbe simán megy ki úgy kód, hogy tele van TODO-kkal. Miért jók akkor, ha nem kezdünk velük semmit? 

Ezeket is irtani kell. De hogyan?

• Előfordul, hogy egy üzleti probléma húzódik meg a háttérben. Ezt próbáljuk minél hamarabb tisztázni, és kezeljük új sztoriként (funkcióként), amit egyszer majd lefejlesztünk. (Ha kell majd egyáltalán.)
• Ha a kód túltervezett, sokszor belebukunk abba, hogy az "általános" megoldást nem jut időnk befejezni. Egyszerűsítsük a kódot azonnal.
• Ha tudjuk, hogy hibásan működik a kódrészlet, akkor - ha lehet - azonnal javítsuk ki. Ha nem lehetséges, vigyük fel a hibát a hibakövető rendszerbe (a reprodukálás módjával). Ezzel elősegítjük a tesztelőket abban, hogy ők is részt vegyenek a hiba elemzésében, ellenőrzésében, és egységes rendszerben kezeljük a hibákat.
• Valamibe belekezdünk, de valami miatt úgy döntünk, hogy még nem fejezzük be, mert más dolgunk akadt, vagy máshol simogatjuk a programkódot. Ezekben az esetekben inkább használjunk exception-öket (pl. UnsupportedOperationException). Ez segít nem elfelejteni, hogy valamivel még adósok vagyunk. Felesleges a TODO, a tesztek miatt nagyon hamar kibukik, hogy hol az elfeledett kódrészlet.

Komment = dokumentáció

A komment egyfajta dokumentáció, ezáltal megvan az a hátulütője is, hogy könnyedén elavulttá válik. Míg egy programkódot (a kommenteket nem beleértve) könnyedén tudunk alakítani, refaktorálni, addig a természetes nyelven megírt kommentek ugyanúgy maradnak, ahogy eredetileg megírtuk őket. Még egy érv amellett, hogy a kommunikáció ne a kommenteken, hanem a működő kódon keresztül történjen.

Konklúzió - kulcs gondolatok

A kommentekkel általában a következők a problémák:

• a fejlesztő nincs rákényszerítve arra, hogy "rendes" kódot írjon, ehelyett odarak pár kommentet a kódjához: a későbbiekben, ha változtatni kell (új funkció, hibajavítás) nehezebb a dolgunk,
• széttagolják a kódot, ezáltal rontják az olvashatóságot (kerülgetni kell őket),
• könnyedén elavulnak.

Nem azt akarom kifejezni, hogy a kommentekre nincs szükség, vagy hogy arra törekedjünk, hogy minél kevesebb komment legyen a kódunkban. Inkább azt javaslom, hogy a cél az legyen, hogy olyan kódot írjunk, amelyhez nem szükséges vagy minimálisan kell csak kommentet írni. 

Legyünk tudatosak, következetesek az elnevezésekben! Semmi ne maradjon rejtve, tegyük explicitté, adjunk nevet neki. (Tudok-e nevet adni neki egyáltalán? Ha nem, akkor valami gond van.)

Valóban azt fejezi ki az osztály, mező, metódus, változó neve, amire használjuk? 

Ha egy hibát keresünk, és ránézünk egy metódusra, megértjük-e a működését? Én meg fogom-e érteni később? Mások vajon megértik-e? Hogyan tudom refaktorálni, hogy tényleg érthető legyen?

Nem lehet tökéletes receptet megfogalmazni. A cél viszont egyértelmű: legyen olvasható és karbantartható a kódbázis!