Scrivere commenti in stile PHPDoc

No v’è dubbio che scrivere una buona documentazione è essenziale per il successo di qualsiasi progetto software.
PHPDocumentor è progettato per rendere più facile la creazione della documentazione.
Esso è basato sul sistema Javadoc di Sun, che è un metodo semplice per commentare tutte le funzioni, gli argomenti, variabili e classi in modo che gli sviluppatori possono facilmente riutilizzarli.
Trovare delle regole quando commentiamo e documentiamo il nostro codice è sicuramente un vantaggio,
ispirarsi a PHPDoc consiste nell’inserimento di un blocco di commenti prima di ogni definizione di classe, funzione, o variabile.

Non è obbligatorio in tutte le situazioni (la nostra applicazione funzionerà anche senza), tuttavia è una buona abitudine da prendere, e ne trarremo vantaggio anche nel caso fossimo noi gli unici a mettere le mani sui sorgenti.
Ogni blocco di commento inizia con una descrizione, seguita da una serie di uno o più parametri opzionali.
Ad esempio, riguardo all’aggiunta di commenti in stile PHPDoc ad una funzione, è necessario specificare i parametri di input e i dati di ritorno.

Il seguente codice mostra un esempio di commento PHPDoc style, per una semplice funzione definita dall’utente:

La prima cosa da notare è come il blocco dei commenti comincia.
Il gettone / ** indica appunto che un blocco commento PHPDoc sta iniziando. La prima riga del blocco è una breve descrizione.
Di solito uso soltanto il nome della classe, funzione o variabile. La sezione successiva del blocco di commento è una descrizione più dettagliata.
Qui provo a descrivere quello che la classe, funzione o una variabile fa, non come funziona.
Eventuali considerazioni specifiche sulla funzionalità meglio inserirli come commenti standard all’interno del codice.
La sezione finale del blocco di commento contiene i diversi parametri. Ogni parametro inizia con un carattere @, seguito dal nome del parametro, seguito a sua volta da una breve descrizione di cosa il parametro rappresenta.
In questo esempio, è possibile visualizzare i parametri @param e @return.
Il primo viene utilizzato per specificare gli argomenti della funzione: in primo luogo, il tipo di argomento (in questo caso, il nostro primo argomento è una stringa), accanto, il suo nome (che in questo caso è $nome) ed infine, una breve descrizione di ciò che il dato di input deve contenere.
Il parametro @return è usato per dare informazioni sui dati restituiti dalla funzione: il tipo di dati, seguito da una breve descrizione di ciò che i dati di ritorno contengono.

Ricordate, a volte, la qualità della documentazione può essere anche più importante della qualità del codice stesso!

Tips

Anche se non richiesto, la convenzione usuale è quella di includere un asterisco all’inizio di ogni riga del blocco / ** ... * /.
Questo serve principalmente per migliorare la leggibilità del commento e soprattutto per identificare più facilmente interi blocchi PHPDoc.

Risorse

http://www.phpdoc.org/tutorial.php