Szinte minden programozási nyelv tartalmaz valamilyen beépített kommentezési lehetőséget. Vagyis magának a nyelvnek a szintaxisa teszi lehetővé, hogy apróbb megjegyzéseket helyezzünk el szoftverünk forráskódjában.
Nem tudom, hogy statisztikailag hány fejlesztő szokta ezeket a lehetőségeket kihasználni, de szerény tapasztalataim alapján úgy gondolom, hogy nem annyira rossz a helyzet ezen a téren, mint azt gondolnánk (lehet, hogy tévedek.)
A legtöbb fejlesztő ugyanis “kommentezik” valamilyen formában, és ezt én pozitívumként értékelem, hiszen az egyedi és sok esetben kesze-kusza kommentezési módszerek még mindig jobbak annál, mintha semmilyen kommentek nem születnének egy fejlesztés során.
Persze láttam már olyan kommenteket is, melyek helyett jobb lett volna a semmi 🙂 A kommentezés tehát meglehetősen elterjedt.
Mikor nem elég az egyedi, rövidke komment? Egyáltalán miért kommentezünk?
Addig, amíg saját magunk tartunk karban egy forráskódot elegendő lehet egy olyan, egyedi kommentezési stílus, melyet mi magunk megértünk, de egy céges környezetben – illetve, ha már ketten-hárman is hozzányúlhatnak a forráskódhoz ez a megoldás szűkösnek bizonyulhat, gondolom mindenkinek nyilvánvaló, hogy miért. 🙂
Sokféle megoldást kitalálhatunk.
Készíthetünk például az egyedi kódolási konvenciókhoz hasonló, kommentezési konvenciókat; melyekben lefektetjük a kommentezésünk alapszabályait – idővel azonban rá fogunk jönni arra, hogy ez kevés, mert át fogjuk hágni saját szabályainkat és semmivel sem leszünk előrébb akkor, ha egy fejlesztési kézikönyvet vagy segédletet, esetleg egy függvény-gyűjtemény szerű leírást szeretnénk készíteni a kódunkhoz.
“Mi a megoldás?” – kérdezhetnénk ilyen csúf, reklám-szlogen szerű módon, várva, hogy egy miszter Proper formátumú, kopasz megoldóember előugrik és megmondja a megoldást.
🙂 Nem hinném, hogy a programozásban lennének ilyen szuper-megoldások (hozzáteszem a háztartási tisztításban sincsenek, csak ezt hazudják…). Én inkább a szerény, lehető legjobb és fejlődőképes megoldásokat keresném.
Egy ilyen megoldás lehet a phpDocumentor, erről szeretnék írni néhány mondatot.
A phpDocumentor a Javadoc-hoz hasonló, komplex dokumentációk megvalósítását lehetővé tevő eszköz, egyedi és bővíthető szabályokkal, melyek azonban a rugalmasságuk mellett mégis átláthatóak maradnak.
Telepítése.
Telepíteni nagyon egyszerű, letöltés után egy kell hozzá egy webszerver, PHP és Pear. Kicsomagoljuk egy mappába, majd elindítjuk a következő URL-en:
http://localhost/PhpDocumentor/docbuilder/
ami persze lehet bármi más aszerint, hogy hová telepítettük.
Telepíthetjük így is:
$ pear install PhpDocumentor
A hivatalos oldalukon találhatunk egy gyorstalpaló szerű leírást, melyben a telepítésről és sokminden másról is találhatunk segédleteket:
A megfelelő konfigurálás után szinte bármilyen formátumban generáltathatunk a megfelelően felkommentezett projektjeinkről dokumentációt. A fenti dokumentációban megtalálható, hogy milyen kapcsolókat alkalmazhatunk, ezekből biztosan nem fogjuk mindet használni, a mi dolgunk mérlegelni azt, hogy az adott projekt milyen bonyolultsági szintű fejlesztési dokumentációt igényel, hiszen például egy API sokkal részletesebb leírást kívánhat, mint egy egyszerű mikroportál, vagy egy cron alkalmazás.
Nem célom a phpDocumentor-hoz súgót készíteni, csupán arra szeretném a figyelmet felhívni, hogy jó lenne ha használnánk ezeket az eszközöket.
A Wikipédián található egy másik, de nagyon jó leírás:
http://en.wikipedia.org/wiki/PHPDoc
Amit még kiemelnék, hogy ez a fajta kommentezési mód egyáltalán nem szűkül be arra, hogy generálhatunk statikus dokumentumokat a kódunkból, a lehetőségeink ennél jóval szélesebb skálán mozognak. Például a @todo tag használatával nyomon követhetjük a kódban bennemaradt nem végleges, nem kifejtett részeket és még folytathatnám a nagyszerűbbnél nagyszerűbb lehetőségeket.
A következő nagyszerű eszköz a Doxygen, mely nem PHP-ban lett írva, hanem egy C++-ban, de ennek ellenére nagyon sok platformra elérhető.
A Doxygen egy varázslóval “DoxyWizard” ellátott alkalmazás, egy grafikus felületen állíthatjuk be a projektünkhez kapcsolódó egyedi kapcsolókat, megadhatjuk a generátor által készített output formátumát ami lehet HTML, CHM, LaTex, RTF, van a varázsló mellett van szakértői mód is, ahol ezernyi beállítást találunk.
Látható, hogy többféle eszközt használhatunk a kommentjeink feldolgozására, tehát a hangsúly inkább az azon van (és ez nagyon fontos szerintem), hogy helyesen kommentezzünk!
Ez elsőre triviálisnak tűnhet, de egyáltalán nem az. Talán legkönyebben úgy érthetjük meg ennek a jelentőségét, ha elkezdünk játszani a kommentekkel és a tagokkal, majd generálunk néhány dokumentációt.
Látni fogjuk, hogy a legenerált dokumentációknak abban az esetben szinte semmi értelme nem lesz ha a kommentjeink nem következetesek, átgondoltak és letisztultak! Ha generálás után, (például HTML formátumban) végignézzük a generált dokumentációkat azonnal kiütköznek a félmondatok, helyesírási hibák, a copy+paste-val másolgatott, oda nem illő szövegrészek, a kód adatlapjával (verzió, dátum, szerző stb.) összefüggő hiányosságok, a kapkodás és az egyéb hiányosságok. Már az első generálás után látni fogjuk, hogy csakis akkor érdemes kommenteznünk ezekkel a módszerekkel ha mindezt komolyan gondoljuk, mert különben semmi értelme nem lesz az egésznek és soha nem lesznek olvasható, használható dokumentációink a kódjainkról.
A wikipédián a Doxygenről:
http://en.wikipedia.org/wiki/Doxygen
Ugye, hogy nem is olyan egyszerű jól kommentezni?
De szerintem nagyon megéri és már egy kisebb cégnél is kincset érhet az erre fordított idő és energia.
Janos's blog 
szia,én a phpSimpleDoc-ot használom, ez PHP keretrendszereket is támogat