PHP: Commentare con stile con Doxygen
Con questo articolo affronteremo un'argomento che è la gioia e dolore dei programmatori: commentare il proprio codice sorgente.
Commentare il nostro codice sorgente non solo ci facilita la vita durante il debug del codice ma ci aiuta a capire cosa fa una determinata funzione o metodo.
Inoltre commentare correttamente il codice ci aiuta anche in fase di coding. Oggigiorno la stragrande maggioranza degli IDE supporta l'autocompletamento del codice e commentare il codice ci aiuta anche per capire cosa fa un determinato metodo e che argomenti servono, senza che è necessario aprire il file che contiene il codice.
Un utilissimo tool che ci aiuta in questa cruciale fase è Doxygen.
Doxygen
Doxygen è un applicazione multipiattaforma (Windows, Linux, MacOSX, etc.) che permette di creare documentazione dal codice sorgente (C, C++, Perl, Python, PHP, Java, etc.).
Grazie all'utilizzo di particolari “comandi” inseriti nel codice sorgente permette di creare una documentazione accurata del nostro codice con tanto di grafici (grazie a Graphziz) con le relazioni tra classi e strutture.
Un esempio
Comandi più utilizzati
| Comando | Descrizione | Esempio |
|---|---|---|
@var <tipo> | Indica la dichiarazione di una variabile | /** * Description * * @var string|array */ public $data = array(); |
@param <tipo> <argomento> <descrizione> | Dichiara un argomento di una funzione o metodo | /** * Description of function|method * * @param array $things Description * @return boolean Description */ function my_func($things) { // ... return true; } |
@return <tipo> <descrizione> | Dichiara il valore restituito da una funzione o metodo | |
@code … @endcode | Crea una sezione che mostra un esempio di codice | /**
* @code
$my_class = new MyClass;
$my_class->foo('bar');
@endcode
*/
|
@see <link> | Indica un link ad una risorsa, una classe, metodo o funzione | /**
* @see http://example.org
* @see substr()
* @see MyClass::myMethod()
*/
|
Maggiori informazioni
- Doxygen - http://www.stack.nl/~dimitri/doxygen/
- Graphviz - http://graphviz.org/