Questa è la traduzione dell'articolo Successful Strategies for Commenting Code di Ryan Campbell, pubblicato originariamente su Particletree l'1 agosto 2005. La traduzione viene qui presentata con il consenso dell'editore e dell'autore.
Commentare il vostro codice è per certi versi come pulire il vostro... bagno. Non si ha mai voglia di farlo ma è una cosa che dà poi una migliore esperienza a noi e ai nostri ospiti. Dal momento che recentemente ho adottato un mio nuovo e personalissimo mantra per usare spesso e nel modo appropriato i commenti nel codice che scrivo, ho speso un po' di ore per fare delle ricerche sulle mie migliori strategie per ottenere una maggiore leggibilità dei commenti e per poterli riusare al meglio. Ne è uscita una raccolta di linee guide che presenterò in questo articolo.
È stato incredibile scoprire la mole di informazioni disponibili sull'argomento. Ci sono questioni piuttosto complicate, ma di fatto quella fondamentale è: "Cosa significa 'spesso e nel modo appropriato'?". Le linee di pensiero sono davvero tante. Ecco la sintesi.
Tipi di commento
Commentare direttamente il codice - Questa modalità si riferisce all'adozione di nomi di variabile che siano descrittivi e auto-esplicativi. È una forma minimale di commento, e ha in genere questa forma:
function addUserToDatabase(userName, userAge)
Senza alcuna informazione aggiuntiva, diciamo che la funzione aggiungerà un nome utente (userName) e l'età dell'utente (userAge) in un database. Un'implementazione di questa strategia è chiamata notazione ungara.
Commentare nel corpo del codice - Questo tipo di commento si trova in genere alla fine di una riga di codice, ma possiamo usarlo per riferirci anche a commenti che si trovino all'interno di una funzione. È la forma più tipica e di base di commento:
function calculateHitPoints(cUser) {
var nStrength = document.getElementById("enemyStrength").value; // grab current enemy strength
// subtract user size : small = 1, medium = 2, large = 3
var nDamage = (nStrength * 3) - cUser.nSize;
return cUser.nCurrentHitPoints - nDamage;
}
Commentare una funzione - Questo tipo di commento si ritrova nelle righe che precedono una funzione e in genere rivelano le informazioni e i dettagli più rilevanti sulla funzion stessa. Nello specifico sono informazioni che includono i parametri, i valori restituiti e dettagli sulla logica della funzione:
/*
* Summary: Calculate hitpoints after attack using formula
* new = current - ((enemyStrength*3) ? size)
* Parameters: cUser - object containing hero's stats
* Return: Boolean indicating life or death
*/
function calculateHitPoints(cUser) {
?
} // end calculateHitPoints
Commentare una clase o una pagina - Sono commenti che si riferiscono ad un'intera pagina o ad oggetti di primo livello presenti nel codice. In genere contengono una panoramica, la data dell'ultima modifica, i file associati, l'autore, informazioni di contatto. Inoltre, possono contenere eventualmente un generico pie' di pagina in fondo. Il mio collega Kevin ha scritto alcuni ottimi template per craere commenti di questo tipo nel suo articolo sull'uso dei template XHTML:
/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Title :
Author :
URL :
Description :
Created :
Modified :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/
Commenti funzionali
Quando si sviluppa nel contesto di un team, l'uso di modi standardizzati per comunicare il passo successivo nel processo sono un grande modo per scambiare informazioni con gli altri membri del team e per rendere più efficiente l'intero processo. In genere, per questi casi, si parla di commenti funzionali:
I commenti funzionali servono ad un unico scopo: aggiungere funzionalità al processo di sviluppo (Bernhard Spuida - The fine art of commenting)
Questi commenti non ci dicono nulla sul codice, ma forniscono documentazione su ciò che deve essere fatto o su quello che è stato già fatto. Ecco una lista di tipologie di commenti che potreste usare nel vostro codice:
- TODO: Una frase chiave che specifica ciò che deve essere compiuto come passo successivo e che andrebbe messa nella riga dove la parte di codice successiva troverà posto.
- BUG/FIX: Documenta uno specifico bug, o un fix apportato ad un bug. Il commento andrebbe inserito sopra la riga a cui si riferisce. Se si usa un software per il bug tracking, si dovrebbe sempre includere l'id del bug.
- TEAMNAME: Questo commento è in genere diverso nei diversi ambiti di lavoro, ma è usato per richiamare l'attenzione di un certo programmatore o di un team. Per esempio, potremmo voler far sapere al team dell'Intelligenza Artificiale perché abbiamo compiuto una certa scelta: useremmo esattamente questo tipo di commento. Per ulteriori informazioni sul tema si può leggere The art of code documentation di Drew Sikora.
Oltre a queste frasi o parole chiave, ci sono in giro programmi che documentano il codice basandosi su commenti standard. Sebbenecon questi software ci sia comunque spazio per errori, vale la pena provarli. Due semplici suggerimenti: XML Comments e JavaDoc.
Migliorare la leggibilità dei commenti
In un mondo ideale, leggere del codice sarebbe come leggere un libro. Purtroppo, il codice viene scritto affinché un computer lo interpreti e lo esegua, non per essere letto da esseri umani. Ma i commenti sono un ottimo modo per fornire un contesto al vostro codice: così, saltando da un punto all'altro, si sa sempre dove ci si trova. Ecco alcuni trucchetti per migliorare la leggibilità.
Paragrafi commentati - Scrivete codice e commenti sotto forma di paragrafi. In 10 Essential Development Practices, Damian Conway suggerisce che noi tutti dovremmo "spezzare ogni pezzo di codice in sequenze che portano a compimento un singolo task".
Far precedere i commenti da una riga bianca - Facendo così si crea una netta separazione tra il codice e i commenti. Ed è anche più piacevole da un punto di vista visivo.
Usare in modo appropriato l'indentazione - Assicuratevi che i commenti siano ben indentati rispetto alla riga a cui si riferiscono. In più, fate in modo che commenti simili siano allineati nel modo giusto. Ecco un esempio:
var MAX_USERS = 2 //all players
var MAX_POINTS = 100000 //needed to win game
Non insultate l'intelligenza altrui - Non tutti i commenti sono produttivi e utili. Troppi commenti possono rendere il codice ancora più illeggibile. Un esempio:
for(i = 0; i < object.length; i++) { //loop until i hits max length
Non è design! - Vedo che molte persone usano caratteri strani dappertutto. Non è necessario. È una pratica che distrae. Più semplice è, meglio è.
Create uno stile consistente - Ci sono molte opinioni sul modo migliore di commentare il codice. Alcuni ritengono che i commenti dovrebbero essere dettagliati al punto che anche un non programamtore sia in grado di seguire la logica; altri ritengono di doverli usare come puro e semplice supporto. La cosa più importante è adottare uno stile consistente. Ciò aiuta chi legge a sapere cosa aspettarsi quando esamina diversi vostri progetti.
Commentate mentre scrivete il codice - Le posssiblità che vi mettiate a commentare il codice una volta portato a termine un progetto sono poche. Fatevi un favore e commentate mentre scrivete.
Commentare in fase di scrittura vi costringe a riflettere sulla logica del progetto, per far sì che sia sempre quella giusta. Inoltre, i commenti saranno molto più accurati, dal momento che vengono fatti quando i meccanismi di funzionamento del progetto sono freschi nella vostra mente.
Riusabilità dei commenti
Il concetto più interessante in cui mi sono imbattuto facendo un po' di letture sui commenti è quello relativo alla "riusabilità dei commenti". È quello a cui pensiamo quando scriviamo codice CSS o Javascript per minimizzare il tempo necessario ad effettuare eventuali cambiamenti nel futuro. Gli stessi principi funzionano parlando di commenti al codice. Ecco un esempio.
Immaginiamo di avere un campo di testo che viene modificato:
document.getElementById("myTextbox").style.width = "100px"; // change textbox width
Quel semplice commento messo in coda alla riga non è riusabile. Se per esempio un giorno volessimo cambiare l'input di testo con una select? Dovremmo cambiare anche il commento.
Ci sono poi altre questioni. È accettabile commentare la fine di un blocco di codice, in questo modo?
function calculateHitPoints(cUser) {
---
} // end calculateHitPoints
In questo caso non ho una risposta univoca. Da una parte non commenterei la fine di ciascun blocco di codice. Dall'altra però vedo un beneficio nel commentare la fine di una funzione. Le funzioni in genere rimangono lì, ma i blocchi che contengono la logica si spostano spesso fin quando tutti gli eventuali bug non vengono corretti. Dal momento che in un documento ci sono diversi blocchi di codice, poi, i commenti possono diventare tanti, appesantendo il tutto senza fornire informazioni davvero utili.
Parlando di commenti alle funzioni, Cprogramming.com ha prodotto The Hows and Whys of Commenting, un testo che evidenzia bene l'importanza di usare nomi di variabili riusabili. Usano un esempio di una funzione che calcola la velocità. Invece di dichiarare la funzione così:
function getSpeed(runnerDistance, runnerTime)
si potrebbe renderla riusabile usando una denominazione più generica:
function getSpeed(totalDistance, totalTime)
Così facendo, si calcola logicamente la velocità di qualunque oggetto (un aereo, un'automobile, un treno) e non solo di uno che corre.
Quando poi si parla dell'uso della notazione ungara, devo aggiungere che la questione è un po' controversa e che ha suscitato fiere contrapposizioni. The Good, The Bad and The Ugly crede che sia poco efficiente cambiare il nome di una variabile ogni volta che si cambia il tipo di variabile. Per esempio, 'szEventType' non dovrebbe essere cambiato in 'nEventType' se si decide di renderlo come un numero invece che come una stringa.
A prescindere da come deciderete di agire, ricordate comunque di considerare la riusabilità quando commentate il codice. Più i commenti sono riusabili meno tempo sprecherete.
Ma perché perdere tempo?
Uno dei principali ostacoli nel commentare il codice è convincere sé stessi a farlo. In questo caso è importante la motivazione.
Una documentazione chiara ed estesa è un elemento chiave per creare software che sopravviva e sappia adattarsi (Jeff Raskin - Comments are more important than code)
Per quanto mi riguarda, dopo aver messo in pratica quanto ho appreso durante la mia ricerca nei miei progetti recenti, ho notato significativi miglioramenti nel mio stile di programmazione:
- Scrivo codice migliore - Commentando tutto, sono costretto a ragionare sul perché faccio una cosa piuttosto che semplicemente sul farla funzionare. Ora programmo in maniera più intelligente. Commentare il codice mi ha portato a verbalizzare la logica di programmazione e mi ha fatto pensare due volte su ogni azione, così sono riuscito a ottimizzare il tutto. I commenti alla fine mi fanno fare meno lavoro. Se avessi fatto i commenti dopo aver finito il progetto, avrei certamente sprecato più tempo.
- Mi assicuro un futuro migliore - Non si sa mai chi guarderà il vostro codice né che quando ci si rimetterà mano. Per il futuro, i miei colleghi, chi mi assegna un lavoro, persino la mia mamma sapranno apprezzare il mio investimento in termini di tempo per commentare il codice, semplicemente perché fa risparmiare tempo. E il tempo è denaro (specialmente quando si parla di programmazione).
- Sono orgoglioso del mio lavoro - Uno dei più grandi problemi nella mia vita è quello di lavorare sulla stessa cosa in maniera un po' discontinua. Se sono orgoglioso e soddisfatto di quello che faccio, tutto ciò rimuove questa specie di blocco mentale. Dato che i miei progetti sono ora puliti, flessibili ed efficienti, sono contento di riprendere un lavoro, e questa cosa per me non ha prezzo. Inoltre, è un modo eccellente per fare una buona impressione su chi giudica il mio lavoro.
Un esempio finale
Ho scritto una semplice funzione Javascript per illustrare come, anche se si pensa che tutti i commenti sembrino importanti, certe cattive pratiche possano possono danneggiare la leggibilità del codice. Ecco il risultato:
/-+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_-
// I wrote this script to process a battle between two units.
// The attack member functions do the calculation, but this
// function determines the order of attacks.
// Two valid objects must be passed in, and then the function
// will return true if everything worked ok.
//-+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_+_-
function beginBattle(attacker, defender) {
var b; // boolean to hold life or death
var teamCount; // counter for loops
if(defender.agility > attacker.agility) {
b = defender.attack(attacker);
}
// if there was a previous strike, make sure he is still alive then process the attack
if(b) {
b = attacker.attack(defender);
}
// see if any teammates want to counter attack
// loop through the defenders teamates starting at i = 0
for(teamCount = 0; teamCount < defender.team.length; i++) {
var teammate = defender.team[teamCount]; //individual teammate
if(teammate.counterAttack = 1) { // 1 means they have counter attack enabled
b = teammate.attack(attacker);
}
}
// make sure that somewhere in here death processing is handled.
return true;
} // end function
Non è terribile, ma potrebbe essere meglio. Usando la stessa funzione, applicheremo alcune delle linee guida che abbiamo imparato:
*
* Summary: Determine order of attacks, and process each battle
* Parameters: Creature object representing attacker | Creature object representing defender
* Return: Boolean indicating successful fight
* Author: Ryan Campbell
*/
function beginBattle(attacker, defender) {
var isAlive; // Boolean inidicating life or death after attack
var teamCount; // Loop counter
// Check for pre-emptive strike
if(defender.agility > attacker.agility) {
isAlive = defender.attack(attacker);
}
// Continue original attack if still alive
if(isAlive) {
isAlive = attacker.attack(defender);
}
// See if any of the defenders teammates wish to counter attack
for(teamCount = 0; teamCount < defender.team.length; i++) {
var teammate = defender.team[teamCount];
if(teammate.counterAttack = 1) {
isAlive = teammate.attack(attacker);
}
}
// TODO: Process the logic that handles attacker or defender deaths
return true;
} // End beginBattle
Il codice, secondo me, è ora più piacevole da leggere e guardare, e sono bastati piccoli cambiamenti. Intanto abbiamo applicato la regola della consistenza. Tutti i commenti sono preceduti da una riga bianca, iniziano con una lettera maiuscola, sono indentati nel modo giusto. Poi, le variabili tipo 'b' sono state cambiate in cose tipo 'isAlive' per renderle autoesplicative. Infine, è stato aggiunto un 'TODO' per evidenziare dove applicare i prossimi interventi.
Costruite un vostro stile
Ora, c'è un gran numero di persone che pensa al codice come ad una forma di espressione personale. È dunque importante per me evidenziare come quelle qui presentate non sono le uniche strategie possibili. Vorrei che ciascuno di voi camminasse invece con le proprie gambe, iniziando a capire per prima cosa i benefici che nascono da una buona strategia nel commentare il codice. Raccomanderei ad ognuno di voi di sviluppare una serie di linee guida in base a quello che si ritiene importante in ogni situazione.
