Commenti JavaScript

Introduzione

Questo capitolo tratta tutto ciò che serve per scrivere buoni commenti JavaScript: le due sintassi di commento (// per i commenti a riga singola e /* */ per i commenti a blocco), i doc-comment JSDoc per documentare le funzioni, la differenza tra commenti utili e dannosi, e come disabilitare del codice durante il debug. I commenti sono testo che il motore JavaScript ignora completamente durante l'esecuzione — esistono esclusivamente per gli esseri umani. Spiegano il codice a chiunque lo legga in seguito, incluso il tuo sé futuro e i tuoi colleghi. Poiché vengono rimossi dall'esecuzione, i commenti non hanno alcun costo a runtime. (Una direttiva correlata che viene letta dal motore è "use strict"; nonostante sembri una stringa all'inizio di un file, cambia il modo in cui il codice viene eseguito — consulta il capitolo sulla modalità strict.)

Perché i commenti sono essenziali in JavaScript

Commentare il codice può sembrare secondario, ma svolge un ruolo fondamentale nella programmazione. Contribuisce a:

• Documentazione del codice: per spiegare la logica complessa o il ragionamento alla base di determinati segmenti di codice.
• Leggibilità del codice: per migliorare la comprensione del flusso e delle funzionalità del codice.
• Debugging: per abilitare o disabilitare facilmente parti di codice durante i test o il debug.
• Collaborazione in team: per aiutare gli altri sviluppatori a comprendere il tuo processo di pensiero.

Tipi di commenti JavaScript

JavaScript supporta due tipi principali di commenti:

Commenti a riga singola

I commenti a riga singola iniziano con // e si estendono fino alla fine della riga corrente. Tutto ciò che segue // su quella riga viene ignorato. Possono stare su una propria riga oppure alla fine di una riga di codice (come commento inline):

// This whole line is a comment
let a = 5, b = 10;

let sum = a + b; // inline comment: add the two values

Poiché un commento // si estende solo fino alla fine della riga, la riga successiva torna ad essere codice normale — non è necessario "chiuderlo".

Commenti multi-riga

I commenti multi-riga (detti anche commenti a blocco) iniziano con /* e terminano con */. Tutto ciò che si trova nel mezzo viene ignorato, anche su più righe. Usali per spiegazioni più lunghe:

/*
  Returns the sum of two numbers.
  Both arguments are expected to be numbers;
  passing strings will concatenate instead of add.
*/
function add(a, b) {
    return a + b;
}

È possibile usare la sintassi a blocco anche nel mezzo di una riga, ad esempio per etichettare un argomento: setTimeout(run, 1000 /* ms */).

Attenzione — i commenti a blocco non si possono annidare. Un */ chiude il commento alla prima occorrenza, quindi racchiudere del codice che contiene già /* ... */ in un altro commento a blocco genera un errore. Il */ interno chiude il commento anticipatamente e il resto diventa codice attivo:

/*
  /* inner */
  alert('this still runs!');
*/

Copia

Per commentare una regione che contiene commenti a blocco, usa invece // su ogni riga.

Commenti buoni e cattivi: spiega il perché, non il cosa

La regola più utile: commenta il perché, non il cosa. Il codice già dice cosa fa; un buon commento cattura l'intento, il compromesso o il vincolo sorprendente che il codice non riesce a esprimere da solo.

// Bad: just restates the code — adds noise, can go stale
let total = 0; // set total to 0

// Good: explains a non-obvious constraint
const RETRY_LIMIT = 3; // the payment API rejects bursts above 3 calls/sec

Preferisci il codice auto-documentante ai commenti quando possibile. Una variabile ben nominata o una piccola funzione spesso elimina del tutto la necessità di un commento:

// Needs a comment because the intent is hidden:
if (u.a && Date.now() - u.l < 86400000) { /* active in last 24h */ }

// No comment needed — the names say it:
const isActive = user.isVerified && wasSeenInLast24Hours(user);
if (isActive) {
  // ...
}

Alcune linee guida aggiuntive:

1. Tienili aggiornati. Un commento che contraddice il codice è peggio di nessun commento — i lettori non riescono a capire di quale fidarsi.
2. Sii conciso. Spiega il ragionamento, non ogni singolo passaggio.
3. Non commentare codice morto in modo permanente. Eliminalo; il controllo di versione lo ricorda.

Commentare il codice

Durante il debug spesso si vuole disabilitare una riga o un blocco senza eliminarlo. Anteponi // a una riga, oppure racchiudi una regione in /* */:

let value = compute();
// console.log('Debug:', value); // temporarily silenced

/*
expensiveLogging(value);
sendToAnalytics(value);
*/

Questo è utile per isolare quale parte del codice causa un problema. Molti editor supportano questa funzione tramite una scorciatoia da tastiera. Consulta il capitolo Console API per alternative più pulite ai resti del debug con console.log.

Marcatori TODO e FIXME

Una convenzione comune è contrassegnare il lavoro non completato con TODO (qualcosa da fare in seguito) o FIXME (un bug noto). Editor e linter possono elencarli automaticamente:

// TODO: optimize this loop for large data sets
// FIXME: breaks when input is an empty array

JSDoc: documentare le funzioni

JSDoc è uno standard per documentare le funzioni tramite un commento a blocco speciale che si apre con /** (due asterischi). Tag come @param e @returns descrivono gli input e l'output. Gli strumenti e gli editor leggono questi commenti per mostrare suggerimenti inline e per generare documentazione HTML.

/**
 * Adds two numbers together.
 * @param {number} a - The first addend.
 * @param {number} b - The second addend.
 * @returns {number} The sum of a and b.
 */
function add(a, b) {
    return a + b;
}

console.log(add(2, 3)); // 5

JSDoc si abbina particolarmente bene alle funzioni: documentare parametri e tipi di ritorno rende chiaro il contratto di una funzione senza doverla leggere nel suo corpo. Altri tag comuni includono @throws, @example e @deprecated.

Conclusione

Incorporare commenti efficaci in JavaScript non è solo una pratica di programmazione, ma anche una competenza comunicativa. Contribuisce in modo significativo alla manutenibilità e alla scalabilità del codice. Padroneggiando i commenti JavaScript, non solo migliori il tuo codice, ma potenzi anche la collaborazione con gli altri nel processo di sviluppo.

Ricorda: un codice ben commentato è il riflesso di uno sviluppatore attento e professionale. Sfrutta la potenza dei commenti e osserva come il tuo codice JavaScript si trasformi in un patrimonio più accessibile e manutenibile.

Pratica