phpDocumentor : cum să-ţi documentezi şi să asiguri calitatea proiectelor PHP?

Eu 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ă

Rezultatul final

O documentaţie elegantă a proiectului.