L’arte di commentare: consigli utili

Se un “esempio” può valere più di mille parole, per un programmatore un “commento” può valere ore e ore di lavoro! Commentare il codice è spesso un’operazione noiosa e, nel momento della stesura del codice, sembra sempre un’attività inutile. Al contrario, soprattutto quando si riprendono vecchi codici, l’aver inserito i giusti commenti può risultare infinitamente utile per ricostruire percorsi mentali ormai dimenticati. Fortunatamente, per chi come me sviluppa sul Web, si ha l’enorme vatanggio di poter commentare quasi tutto il codice allo stesso modo! Il doppio slash (//) o il contenimento tramite slash asterisco e asterisco slash (/* e */) è supportato praticamente da tutti i lunguaggi di sviluppo di uso comune, derivati in pratica tutti dal C: Javascript, Actionscript, PHP, …

Come header, ad esempio, io uso sempre una struttura di questo tipo, identica per quasi tutti i linguaggi che uso:

1
2
3
4
5
6
7
8
9
/*
** @name        : main.as
** @description : classe principale del progetto Flash
** @author      : =undo=
** @web         : http://www.undolog.com
** @email       : g.fazioli@undolog.com - g (dot) fazioli (at) undolog (dot) com
**
** @ver         : 1.0
*/

la stessa identica sintassi può essere utilizzata anche per Javascript o PHP. Uso il simbolo @ (at), la chiocciola, così da rintracciare i commenti all’interno del codice in modo rapido, ultile per i commenti a funzioni (metodi), eventi e proprietà:

1
2
3
4
5
6
7
8
/*
** @name        : collapse()
** @description : genera un parse di tipo a
** @params      : value    - valore di collapse
**              : type     - tipo di collapse
** @result      : true se ok, false se errore
** @seealso     : uncollapse()
*/

In Actionscript, dove sia ha più spesso a che fare con classi, distinguere tra metodi (pubblici o privati), eventi e proprietà può risultare comodo durente lo scorrere di un codice:

1
2
3
4
5
/*
** @name        : ontopdown()
** @description : (event) - trigged quando l'elemento è attivo
** @seealso     : ontopup()
*/
1
2
3
4
5
/*
** @name        : color
** @description : (property) - get/set il colore di sfondo
** @seealso     : bgcolor
*/

2 commenti a: “ ”

  1. 31 mag, 2008 Chris:

    Vero, direi che oltre ad aiutare te stesso nella rilettura del codice, aiuti anche chi viene dopo di te (nel caso si lavori su progetti condivisi). In questo caso diventa anche una forma di rispetto, lasciare un buon lavoro nelle mani altrui rende più facile la vita degli altri.
    Da qualche parte avevo letto una citazione inglese di qualcuno che diceva:” programma come se quello che viene dopo di te fosse uno psicopatico che sa dove abiti” :-D

    RispondiQuota
  2. 31 mag, 2008 Giovambattista Fazioli:

    @Chris: parole sante! :)

    RispondiQuota

Lascia un commento

TAG XHTML PERMESSI: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> INSERIMENTO CODICE: 
<pre></pre> // blocco generico
                   <code></code> // blocco generico
                   [cc_actionscript][/cc_actionscript] // Actionscript
                   [cc_actionscript3][/cc_actionscript3] // Actionscript 3
                   [cc_css][/cc_css] // CSS Style Sheet
                   [cc_html][/cc_html] // HTML
                   [cc_js][/cc_js] // Javascript
                   [cc_objc][/cc_objc] // Objective-C
                   [cc_php][/cc_objc] // PHP
                   [cc_sql][/cc_sql] // SQL