phpDocumentor : cum să-ţi documentezi şi să asiguri calitatea proiectelor PHP?
7Eu sunt unul dintre adepţii documentării proiectelor pentru că am realizat (şi nu sunt singurul) că o documentaţie bună a codului ne permite ulterior să trecem prin lucrări realizate în urmă cu săptămâni, luni sau chiar ani ca şi cum ar fi fost cu o săptămână înainte de dezvoltare(bine, poate două).
Da, majoritatea dintre noi avem şi scuze pentru care nu facem asta :
• documentarea codului nu este cerută de client
• nu avem timp, prea multe lucruri de făcut într-un timp foarte scurt
• prea multă muncă şi nimeni nu analizează codul mai târziu
• de ce aş face asta?
• avem o taxa suplimentară pentru documentaţie dar în general clienţii refuză oferta
• etc. etc. etc.
Există mereu scuze pentru treaba aceasta, unele mai originale decât altele. Totuşi, tu ca şi dezvoltator dintr-o firmă sau ca manager al uneia doreşti să atragi cât mai mulţi clienţi. Mai mulţi clienţi sunt atraşi de proiecte de calitate şi de atenţia la detalii. Proiectele de calitate şi atenţia la detalii pot fi subliniate printr-un raport. În raport ar putea fi inclusă şi prezenţa comentariilor din cod ce permit revizuirea regulată mult mai eficientă a codului. Toate acestea îţi aduc mai mulţi bani.
Mai mult decât atât, de multe ori firmele îşi construiesc propriile engine-uri, unelte şi frameworkuri, care de care mai complexe şi utile. Totuşi, dinamismul unei firme implică şi sosirea unor noi dezvoltatori, la fel şi plecare altora. Cum puteţi menţine actualizate aceste aplicaţii interne dacă un dezvoltator nou nu are habar de cum sunt lucrate? Întradevăr, vă puteţi afirmand că dacă repsectivul se pricepe atât de bine în domeniul său ar trebui să înţeleagă. Perfect adevărat, dar lucrul acesta s-ar întâmpla de câteva ori mai încet, deci dumneavoastră, ca reprezentant al firmei veţi pierde nişte bani.
Cum documentezi proiectul tău PHP?
Scrierea unei documentaţii nu este chiar atât de dificilă pe cât unii îşi imaginează şi mai ales, nu necesită un efort prea mare, dar bucuria pe care o veţi avea la revizuirea codului va fi imensă. Pentru documentarea bibliotecilor, claselor şi funcţiilor ar trebui să folosiţi nişte şabloane special predefinite pentru a putea construi la sfârşit documentaţia.
Spre exemplu, un şablon pentru o bibliotecă de clase ar putea arăta astfel :
<?php /** * Biblioteca mea geniala * * Aceasta biblioteca de clase vine cu functii suplimentare * pentru framework x.y.z, compatibil pana la versiunea v.05. * * @category My * @license Copyright 2011 © WorldIT.info, Inc. - All rights reserved */
Ceva asemănător puteţi folosi şi pentru descrierea claselor.
/** * Clasa_mea_super_geniala * * Aceasta clasa ma ajuta sa fac clatite v2.0 in * frameworkul folosit de companie. * * @package Clasa_mea * @subpackage Clasa_mea_super_geniala * @version $Id:$ */ class My_Amazing_Component_Class { }
La fel, pentru funcţii.
/** * Pentru a determina pozitia intr-o harta 2D * avem nevoie de latitudine si longitudine. * * @param float $latitude Latitudinea pozitiei. * @param float $longitude Longitudinea pozitiei. * @return string Un url catre pozitia respectiva de pe harta. * @throws OutOfBoundsException cand valorile sunt invalide. */ public function findTheSpot($latitude, $longitude) { }
Cum sa construiesti documentatia automata?
Dacă ai finalizat proiectul, ai scris şi comentarii, nu ne rămâne decât să generăm documentaţia folosind un API pentru acest lucru. Există unelte foarte promiţătoare precum Doxygen, DocBlox, phpdocgen şamd. Totuşi, populară rămâne în continuare phpDocumentor, o unealtă simplu de folosit ce cu ajutorul a câţiva parametri reuşeşte să genereze documentaţii de înaltă calitate.
user@server $: phpdoc \ -o HTML:frames:earthli \ -ric docs/README.txt \ -ti "phpDocumentor Example" \ -dc MyCompany \ -dn My_Amazing \ -d application/models,application/forms,library/My \ -i *.phtml \ -t docs/api
Explicaţia parametrilor :
-o HTML:frames:earthli defineşte template-ul ce va fi folosit, în acest exemplu e folosit earthli
-ric docs/README.txt defineşte fişierele README, INSTALL şi CHANGELOG
-ti „PHPDocumentor Example” titltul
-dc MyCompany stabileşte categoria by default dacă nu este niciuna pusă la dispoziţie
-dn My_Amazing stabileşte pachetul default, la fel, dacă lipseşte definiţia unuia
-d application/models,application/forms,library/My defines lista directoarele ce conţin fişiere php ce trebuie documentate
-i *.phtml defineşte fişiere ce ar trebui să fie ignorate când se realizează documentaţia
-t docs/api defineşte locaţia unde ar trebui salvată documentaţia generată
Dude, se numeste phpDocumentor, nu phpDocumentator :)))
De altfel, eu prefer doxygen pentru ca stie si alte limbaje de programare, nu doar PHP
Foarte interesant articolul. Într-adevăr sunt nişte detalii esenţiale de care foarte mulţi nu ţin cont.
Sugerez pe viitor un articol despre uneltele de integrare, precum Sonar şi Jenkins. Ar fi mai mult decât binevenit.
Mulţumim încă o dată pentru articol 🙂
@Roland Thanks! Nu ma trezisem inca in clipa respectiva. :-)) Da, am lucrat si cu doxygen dar de el voi discuta cu alta ocazie.
@Marian Multumesc pentru sugestii. Vad cum stau cu timpul si poate scriu ceva despre ele. 🙂
Ai uitat sa mentionezi un alt aspect important (desi nu stiu cat de mult se aplica la php). Documentarea codului duce la posibilitatea refolosirii lui intr-un alt proiect. De exemplu cum ai tu clasa ta cu functii pentru harti 2d, o poti adauga ca librari in zend framework si cine stie cand ai un proiect la care ai nevoie de asa ceva. Si mai indicat e sa imparti libraria in sub-librarii (exemplu google-api pentru maps, geometrie 2d pentru calcule, etc). O sa ajungi ca la orice proiect nou ai sa refolosesti cod din proiectele vechi. Asta inseamna un client fericit pentru ca te-ai miscat mai rapid si mai multi bani pentru tine (ca ai parte de proiect deja facuta).
@Dinu: Nu vad de ce documentarea codului duce la refolosirea lui. Daca ai memorie eidetica sau rabdare sa te mai uiti peste cod, poti sa il refolosesti si daca nu e documentat
@Roland: Ce zici tu e valabil pentru proiecte mici spre foarte mici. Cand refolosesti cod trebuie neaparat sa stii daca are posibile limitari, tipuri de teste facute, formatul inputului, formatul outputului, complexitatea, etc. Nu te intereseaza codul in sine ca nu ma refeream la copy-paste.
@Dinu: Memoria eidetica inseamna ca nu uiti nimica ce ai vazut o data, deci nu ai nevoie de documentatie 😛
Lasand gluma la o parte, inteleg la ce te referi, si sunt de acord ca documentatia e necesara, dar nu cred ca fara documentatie nu se poate refolosi o bucata de cod.