This is an old revision of the document!
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 correttamente il codice ci aiuta anche per capire cosa fa un determinato metodo e che argomenti servono, senza la necessità aprire il sorgente 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 partendo dal codice sorgente (C, C++, Perl, Python, PHP, Java, etc.) in diversi formati (man pages, HTML, PDF, CHM, RTF, LaTex, PostScript, 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
<?php /** * Foo Class * * Description of foo class * * @package MyCMS.Foo * @author John Doe <john.doe@example.com> * @copyright (C)2014, John Doe * @license see LICENSE.txt */ class Foo { /** * Things * * @var array */ private $_data = array(); /** * Constructor * * @param array $things */ public function __construct($thighs = array()) { $this->_data = $things; } /** * Get data * * @return array */ public function getData() { return $this->_data; } }
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/