Commenti in JavaScript: //, /* */ e quando usarli

Due tipi di commenti

JavaScript ha due sintassi per i commenti. Un commento su una riga inizia con // e arriva fino alla fine della riga:

// This is a single-line comment
let price = 100; // Comments can also trail code

console.log(price);

Un commento a blocco inizia con /* e finisce al successivo */. Può occupare tutte le righe che vuoi:

/*
  This is a block comment.
  It spans multiple lines.
  The interpreter ignores all of it.
*/

let total = 42;
console.log(total);

Entrambe le forme vengono completamente ignorate dal motore JavaScript. Esistono per le persone: per te, per i tuoi colleghi e per il te del futuro che rileggerà questo codice tra sei mesi.

Commenti su una riga

// è quello che userai di più. Tutto ciò che si trova sulla stessa riga dopo // è un commento; la riga successiva torna a essere codice:

// Calculate the tax-inclusive price
const price = 100;
const taxRate = 0.08;
const total = price * (1 + taxRate); // final amount the customer pays

console.log(total);

I commenti in coda (dopo un'istruzione) vanno bene per note brevi. Se la nota diventa così lunga da andare a capo, spostala su una riga a sé sopra il codice: i commenti in coda lunghi vengono tagliati dagli editor e ignorati da chi legge.

Commenti a blocco

/* */ è utile in due casi: un commento che ha bisogno di più di una riga e un commento che sta in mezzo a un'espressione.

/*
 * Applies a bulk discount when the order qualifies.
 * Rules change per quarter - see pricing spec #214.
 */
function bulkDiscount(quantity, unitPrice) {
    return quantity >= 10 ? unitPrice * 0.9 : unitPrice;
}

// Inline in the middle of an expression:
const area = /* width */ 10 * /* height */ 5;

console.log(bulkDiscount(12, 50));
console.log(area);

Una trappola: i commenti a blocco non si annidano. Il primo */ chiude il commento, anche se pensavi di essere ancora dentro uno esterno:

/* outer /* inner */ still outer */
// SyntaxError - the first */ closed the block,
// and "still outer */" is now invalid code.

Se devi commentare codice che contiene già /* */, usa invece // su ogni riga.

Commentare il codice

Durante il debug vorrai spesso disattivare temporaneamente qualche riga. Funzionano entrambe le forme di commento:

function checkout(cart) {
    const subtotal = cart.reduce((sum, item) => sum + item.price, 0);

    // const shipping = calculateShipping(cart);
    // const total = subtotal + shipping;

    /*
    if (cart.length === 0) {
        throw new Error("Cart is empty");
    }
    */

    return subtotal;
}

console.log(checkout([{ price: 10 }, { price: 20 }]));

Ogni editor ha una scorciatoia per questo, Ctrl+/ su Windows/Linux e Cmd+/ su Mac, che attiva o disattiva // sulle righe selezionate. Imparala una volta: la userai ogni giorno.

Il codice commentato dovrebbe essere temporaneo. Non fare commit di cimiteri di codice morto con sopra // old version, keep just in case. Il controllo di versione si ricorda il vecchio codice al posto tuo. Cancellalo.

Commenta il perché, non il cosa

È l'unica regola che separa i commenti utili dal rumore. Il codice mostra già cosa fa. Un buon commento spiega perché.

Rumore:

// Set x to 10
let x = 10;

// Loop through the array
for (let i = 0; i < x; i++) {
    // Add i to the total
    console.log(i);
}

Questi commenti non dicono a chi legge niente che il codice non dicesse già. Confronta con:

// Stripe caps description at 500 chars - truncate before sending
function prepareDescription(text) {
    return text.slice(0, 500);
}

// Retry once: the auth service has a known cold-start timeout on first request
async function fetchUser(id) {
    try {
        return await api.get(`/users/${id}`);
    } catch {
        return await api.get(`/users/${id}`);
    }
}

Entrambi i commenti si riferiscono a qualcosa che chi legge non potrebbe capire dal solo codice: un vincolo esterno, una stranezza documentata. È questo il livello da raggiungere. Se togliendo il commento nessuno resterebbe confuso, il commento non stava facendo il suo lavoro.

JSDoc: commenti letti dagli strumenti

JSDoc è una convenzione per scrivere commenti a blocco che descrivono le funzioni in modo strutturato. Editor e type checker li leggono e ti danno un completamento automatico e una documentazione al passaggio del mouse migliori:

/**
 * Returns the final price after applying a percentage discount.
 *
 * @param {number} price - The original price in cents.
 * @param {number} percent - Discount percentage, 0 to 100.
 * @returns {number} The discounted price in cents.
 */
function discount(price, percent) {
    return price * (1 - percent / 100);
}

console.log(discount(10000, 20));

È l'apertura /** (due asterischi) a identificarlo come JSDoc invece che come normale commento a blocco. Non ti serve JSDoc su ogni funzione: conviene soprattutto per le API pubbliche, le utility condivise e ovunque i tipi non siano già ovvi dal codice.

Qualche abitudine da mantenere

• Tieni i commenti vicino al codice che descrivono. Un commento dieci righe sopra la riga a cui si riferisce tende a perdere la sincronia man mano che il codice cambia.
• Aggiorna i commenti quando cambi il codice. Un commento obsoleto è peggio di nessun commento: mente attivamente a chi legge dopo di te.
• Preferisci nomi migliori a più commenti. const d = 86400000; ha bisogno di un commento. const MILLISECONDS_PER_DAY = 86_400_000; no.
• Segnala i problemi temporanei con TODO: o FIXME:. Quasi tutti gli editor li evidenziano, e sono facili da ritrovare con grep in seguito.

// TODO: gestire bene i fusi orari quando aggiorneremo la libreria delle date
function daysBetween(a, b) {
    const MS_PER_DAY = 86_400_000;
    return Math.round((b - a) / MS_PER_DAY);
}

const start = new Date("2024-01-01");
const end = new Date("2024-01-15");
console.log(daysBetween(start, end));

Una nota su commenti HTML e JavaScript

Se scrivi JavaScript dentro un file HTML, non confondere i due stili di commento. L'HTML usa <!-- -->; JavaScript usa // e /* */. Dentro un tag <script> funzionano solo le forme di JavaScript:

<script>
    // Corretto: commento JS dentro <script>
    /* Anche questo è corretto */
    <!-- Sbagliato: questo è un commento HTML e romperà il tuo JS -->
    console.log("ciao");
</script>

Per ragioni legate a browser antichissimi, storicamente i browser tolleravano <!-- --> dentro gli script, ma consideralo sbagliato e vai avanti.

Prossimo passo: dichiarare le variabili

Ora che sai annotare il codice, è il momento di scriverne un po'. JavaScript ha tre modi per dichiarare una variabile, let, const e var, e scegliere quello giusto è la prima vera decisione che prenderai su ogni riga. È il prossimo argomento.