Commentare il codice

Commentare il codice è una pratica sempre raccomandata, ma poco tempo in genere viene dedicato al tipo di commenti inseriti. Esistono commenti informativi, commenti essenziali e commenti inutili. I commenti informativi sono per lo più commenti che descrivono il tipo di dati accettati o restituiti da un metodo, o la gerarchia del metodo o della proprietà  all'interno di una classe o di un componente. Sono utili, ma non quanto la descrizione esatta di cià che fa un metodo o della funzione di una proprietà . Questi sono commenti fondamentali, senza i quali sarebbe difficile capire il codice scritto da altri.

Stranamente, in molti framework che ho studiato questo tipo di commenti manca del tutto, ad eccezione del solo codice sorgente di Firefox. Sicuramente è importante sapere che il metodo X restituisce un valore booleano, ma come si è giunti a quell'implementazione? Quali sono stati i passaggi intermedi? Perché quel tipo di parametri? Che rapporto c'è tra il metodo X e gli altri metodi? Esistono dipendenze?

Molti sviluppatori (sia che usino JSDoc o PHPDoc) ritengono che descrivere un componente del codice in modo esteso sia inutile o semplicemente una perdita di tempo. Niente di più sbagliato: infatti da un punto di vista della riusabilità  del codice è certamente molto più pratico e veloce che trascorrere mezz'ora su Skype cercando di aiutare uno sviluppatore che sta leggendo per la prima volta il nostro codice.

I commenti descrittivi sono in assoluto i più utili perché aiutano l'usabilità  e ci risparmiano una notevole fatica.

E i commenti inutili? Sono quel genere di informazioni che non hanno alcuna utilità  per chi legge il codice. Ovviamente non mi riferisco ai TODO e ai riferimenti ai bug esistenti, ma a commenti del tipo:

// inizializzo element su null
var element = null;

A noi non interessa quel tipo di informazione, quanto piuttosto sapere il perchè della scelta del tipo null. Sarebbe stato più utile dire che, dato che quella variabile servirà  a selezionare un elemento nel DOM, quel tipo di valore servirà  come predefinito nel caso in cui l'elemento non esistesse, in modo che in seguito, ad esempio, io possa operare una verifica sul tipo e sapere se il metodo ha effettivamente selezionato un elemento.