Tra i consigli forniti dai programmatori e che capita di leggere su blog e riviste, compare in maniera pressochè continua la frase "commentare il codice". Di qualsiasi linguaggio si parli, sia in ambito desktop o in ambiente web, sembra che commentare il codice sia una pratica da adottare in maniera costante.
Ma in cosa consiste esattamente la commentazione del codice? Vi sono standard precisi da seguire? E' davvero così fondamentale?
Cosa significa "commentare il codice"
Significa inserire delle righe di spiegazione (o di commento appunto) all'interno del codice vero e proprio del programma; tale testo viene distinto e separato dal resto del codice tramite l'utilizzo di marcatori coi quali impostare l'inizio e la fine di un commento.
Non tutti i linguaggi usano gli stessi marcatori per delimitare i commenti, per quanto riguarda Actionscript vi sono due possibilità:
- // usato per i commenti su linea singola
- /* */ usati per i commenti su più linee
Quindi all'interno di un codice Actionscript potremmo inserire dei commenti in questo modo:
Listato 1. Esempio di inserimento di un commento
// Assegno il valore 5 alla variabile a
var a:Number = 5
/* Alla variabile b assegno invece il valore 10,
tale variabile verrà utilizzata in seguito nello script
all'interno di operazioni matematiche
*/
var b:Number = 10
Spesso oltre ai marcatori/delimitatori del linguaggio si tende ad inserire dei caratteri aggiuntivi in modo da evidenziare meglio le aree di commento.
Con gli editor provvisti di colorazione del codice questo metodo si può evitare dato che solitamente i commenti vengono colorati in tonalità piuttosto chiare, ma specialmente all'interno di codici molto lunghi non è raro trovare commenti di questo genere
Listato 2. Esempio di commento
// *********************** Funzione cerca_array *************** //
// Questa funzione si occupa di cercare i termini passati come parametri
// alla funzione all'interno dell'array di dati generato dinamicamente
// ****************************************************** //
Ci sono standard da seguire?
Generalmente no, non vi sono dei veri e propri standard per quanto riguarda i commenti, dato che all'interno dei marcatori necessari per delimitare un commento si può scrivere quello che si desidera e l'unico requisito per la scrittura di un commento è delimitarlo tra gli appositi delimitatori a seconda del linguaggio.
Tuttavia vi sono alcune situazioni in cui può essere utile e necessario seguire delle linee guida, ad esempio quando si vogliono sfruttare dei tool per generare la documentazione di una classe.
Generare automaticamente la documentazione
Uno degli aspetti più utili della commentazione del codice è la possibilità di generare automaticamente, tramite appositi tool, la guida a metodi e proprietà di una classe. Non esiste un generatore "unico" per tutti i linguaggi, ma esistono diversi progetti. Ad esempio per quanto concerne Actionscript uno tra i più noti è ZenDoc, mentre Adobe ha creato ASDoc, reperibile nel Flex SDK e nel Flex Builder.
ZenDoc viene dichiarato compatibile con Actionscript 2 e Actionscript 3, mentre ASDoc sembra più mirato ad Actionscript 3. Queste due soluzioni sono gratuite, ma esistono anche sistemi commerciali come AS2Doc (sembra però sia compatibile solo con Actionscript 2).
Ogni sistema può avere particolari requisiti per la commentazione, ma soprattutto offre un diverso output a livello grafico.
Per capire in dettaglio vediamo:
Ovviamente il codice di partenza è diverso, ma gli esempi rendono bene l'idea di come ogni tool offra un diverso risultato finale a livello di rappresentazione grafica.
Alcuni tool permettono l'utilizzo di template per variare l'aspetto delle pagine HTML di documentazione; ZenDoc è tra questi.
La maggior parte di questi strumenti segue le direttive JavaDoc per creare la documentazione partendo dai commenti, per cui lo sviluppatore ha la fortuna di poter scegliere lo strumento che preferisce per realizzare la documentazione badando principalmente all'aspetto visivo finale senza dover stravolgere i commenti del suo codice qualora decidesse in futuro di utilizzare un altro strumento.
Notiamo che ZenDoc, ASDoc e AS2Doc non analizzano i commenti a singola linea, inoltre usano una sintassi leggermente variata dei commenti multilinea: infatti perchè un commento sia analizzato da questi strumenti deve avere una struttura come la seguente:
Listato 2. Struttura di un commento per essere analizzato
/**
* Testo
* Testo
* Testo
*/
Utilizzo di tag specifici
Poichè non basta scrivere un testo descrittivo perchè un qualsiasi tool sia in grado di trovare automaticamente metodi e proprietà di una classe, questi sistemi hanno bisogno di essere "guidati" per poter generare dei file HTML che prevedano la divisione tra parametri, valori di ritorno, metodi, proprietà ed altro. Per questi ci sono tag e combinazioni specifiche da utilizzare e che indicheranno al tool di documentazione che il testo seguente va rappresentato in un certo modo.
Per esempio, per un metodo che prevede due parametri e la restituzione di un valore booleano, il commento potrebbe essere questo:
Listato 3. Commento di un metodo con due parametri e un valore booleano
/**
* Descrizione del metodo "esempio"
*
* @param param1 Descrizione del primo parametro
* @param param2 Descrizione del secondo parametro
*
* @return Un valore booleano (true o false)
*
*/
public function esempio(param1:String, param2:Number):Boolean {
..//
Con questi tag "aiutiamo" il tool di documentazione a separare gli elementi e a fornire una descrizione più dettagliata del codice.
Altri tag possono essere:
- @see: usato per linkare un altro metodo o un'altra classe correlati alla funzione attuale;
- @throws: usato per documentare un errore che il nostro codice può restituire;
- @example: per inserire nella documentazione un codice di esempio.
Per questi tag conviene fare riferimento alla guida dello strumento scelto, poichè ogni tool può avere particolari combinazioni e requisiti.
Usare codice HTML nella documentazione
Un metodo efficace per evidenziare parti di testo è quello di utilizzare stili come grassetto o corsivo, o si potrebbe voler rappresentare una parte di testo come codice. Poichè le pagine restituite dagli strumenti di documentazione sono dei normali file HTML, è possibile usare i tag per evidenziare alcune parti e in generale per rendere di più facile consultazione la nostra guida. Ecco ad esempio come potremmo migliorare il commento del metodo visto poco fa:
Listato 4. Esempio inserendo codice html
/**
* Descrizione del metodo <code>esempio</code>
*
* <p>Questo metodo compara le due stringhe passate come parametri
* e restituisce il risultato della comparazione</p>
*
* @param param1 Descrizione del primo parametro
* @param param2 Descrizione del secondo parametro
*
* @return Un valore booleano (<strong>true</strong> o <strong>false</strong>)
*
*/
public function esempio(param1:String, param2:Number):Boolean {
..//
Escludere elementi dalla documentazione
Ci sono casi in cui potremmo non voler mostrare determinati parti di testo all'interno della documentazione, magari perchè sono commenti che usiamo noi come riferimento in fase di programmazione ma che non avrebbero utilità per l'utente finale, oppure potremmo voler escludere delle intere parti di codice perchè si tratta magari di metodi interni sfruttati solamente dalla classe e non richiamabili dall'esterno.
In questo caso le variazioni tra un sistema e l'altro sono maggiori, in ASDoc, ad esempio, basta inserire la scritta @private perchè il metodo seguente (e i relativi commenti) non vengano inseriti nella documentazione, ma è anche possibile nascondere parti di testo includendolo tra i tag <span class="hide">....</span>. Generalmente per queste situazioni è consigliabile fare riferimento alla guida del tool.
Non solo commenti
Per generare la documentazione questi strumenti non si basano esclusivamente sui commenti, ma analizzano anche parte del codice stesso dell'applicazione: per questo è importante che classi, metodi e proprietà abbiano dei nomi facilmente identificabili e comprensibili, altrimenti otterremmo una documentazione confusionaria e quindi scadente.
Se abbiamo la necessità di generare la documentazione di una classe, quindi, ricordiamoci che non basterà commentarla in maniera esaustiva, ma anche il codice dovrà essere scritto dando nomi identificativi.
Quale strumento scegliere?
Probabilmente non c'è una risposta: ASDoc genera la documentazione sullo stile di quella di Flex che è attualmente uno dei metodi più comuni, inoltre, essendo una soluzione sviluppata da Adobe e integrata nel Flex Builder e nel Flex SDK può renderla particolarmente gradita agli sviluppatori Actionscript 3, mentre chi utilizza Actionscript 2 potrebbe preferire soluzioni come AS2Doc, che seppur svantaggiato dal fatto di essere a pagamento offre la possibilità di generare l'output in diversi formati, oppure ZenDoc che viene dichiarato utilizzabile sia con Actionscript 2 che con Actionscript 3 e offre la possibilità di creare i propri template per lo stile delle pagine HTML di documentazione. Vi sono poi ancora altri strumenti, ad esempio Natural Docs che supporta molti linguaggi e offre diverse feature, ma il cui sviluppo sembra fermo al 10 Febbraio.
Vanno infine considerati i requisiti e le modalità d'uso di ogni tool. AS2Doc è probabilmente il più intuitivo, dato che offre la possibilità di utilizzare un'interfaccia grafica o in alternativa di essere richiamato tramite linea di comando. Analogamente anche ASDoc può essere richiamato da linea di comando, mentre ZenDoc è quello un po' più "scomodo" da usare in quanto richiede il linguaggio PHP e un browser con Javascript abilitato (a meno di non richiamarlo da linea di comando, allora è sufficiente PHP). Questo implica la necessità di avere un webserver con PHP installato sulla propria macchina, o almeno uno spazio web che supporti tale linguaggio.
