Scrivere commenti in stile PHPDoc
5 Lug
Out Of Date Warning
Questo post è stato pubblicato più di 2 anni fa (il 5 Luglio 2011). Le idee vanno avanti velocemente, le prospettive cambiano quindi i contenuti potrebbero non essere aggiornati. Ti prego di tenere in considerazione questo, e di verificare le informazioni tecniche presenti nell'articolo prima di farne affidamento per i tuoi scopi.
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
<?php /** * miaFunzione * * Una semplice funzione che mostra un messaggio * all'utente basandosi sul suo nome ed età * * @param string $name Il nome dell'utente * @param int $age L'età dell'utente * @return string Messaggio di saluto */ function miaFunzione($name, $age) { $str = sprintf('Ciao %s, la tua età è %d anni', $name, $age); return $str; } ?> |
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.
quello che stavo cercando, grazie
è un piacere