Commenti in Rust

I commenti sono note che lasci nel codice per chi lo legge. Rust li ignora completamente quando compila, quindi non cambiano mai il comportamento del programma. I buoni commenti spiegano perché il codice fa qualcosa, non solo cosa fa.

Commenti di riga

Il commento più comune comincia con //. Tutto quello che segue // su quella riga viene ignorato:

fn main() {
    // Questo è un commento: Rust lo salta del tutto
    println!("Ciao!"); // i commenti possono stare anche in fondo a una riga
}

Output:

Ciao!

▶ Provalo tu

Commenti su più righe

Per una nota più lunga, puoi cominciare ogni riga con //:

fn main() {
    // Questo programma saluta l'utente.
    // Stampa una sola riga di testo.
    // Scritto come primo esempio.
    println!("Ciao!");
}

Output:

Ciao!

▶ Provalo tu

Rust supporta anche i commenti a blocco tra /* e */, che possono estendersi su più righe:

fn main() {
    /*
      Questo è un commento a blocco.
      Può occupare più righe
      senza un // su ciascuna.
    */
    println!("Ciao!");
}

Output:

Ciao!

▶ Provalo tu

In pratica, la maggior parte del codice Rust usa // anche per più righe: è la consuetudine della comunità e funziona bene con le scorciatoie degli editor.

Commentare il codice

I commenti sono comodi per disattivare temporaneamente una riga mentre provi qualcosa:

fn main() {
    println!("Questa viene eseguita");
    // println!("Questa per ora è spenta");
}

Output:

Questa viene eseguita

▶ Provalo tu

Scrivere commenti che aiutano

Un commento che ripete il codice non aggiunge niente. Il codice dice già cosa succede. Un buon commento dice perché, o avvisa di qualcosa che chi legge non può vedere:

fn main() {
    let minutes = 135;

    // Il timer mostra solo ore intere. La divisione tra interi scarta
    // il resto, ed è proprio quello che vogliamo qui.
    let hours = minutes / 60;
    let leftover = minutes - hours * 60; // minuti che non arrivano a un'ora intera

    println!("{hours} h {leftover} min");
}

Output:

2 h 15 min

▶ Provalo tu

Confrontalo con un commento come // dividi i minuti per 60. È vero, ma chiunque sa leggere minutes / 60. L’informazione utile è perché qui dividere va bene.

Qualche altra abitudine che vale la pena prendere:

Tieni aggiornati i commenti. Un commento che non corrisponde più al codice è peggio di nessun commento, perché la gente si fida.
// TODO: è un modo comune per segnare il lavoro non finito, come // TODO: gestire i numeri negativi. Molti editor lo evidenziano e sanno elencare tutti i TODO di un progetto.
In Rust i commenti a blocco si possono annidare. A differenza del C, puoi racchiudere in un altro commento del codice che contiene già un commento /* */, e funziona lo stesso:

fn main() {
    /* Spento per ora:
       println!("vecchio saluto"); /* salutava tutti */
    */
    println!("nuovo saluto");
}

Output:

nuovo saluto

▶ Provalo tu

Commenti di documentazione

Rust ha un tipo speciale di commento che comincia con /// (tre barre). Sono i commenti di documentazione (doc comment): descrivono le funzioni, e Rust può trasformarli in un sito di documentazione navigabile con cargo doc.

/// Somma due numeri e restituisce il risultato.
fn add(a: i32, b: i32) -> i32 {
    a + b
}

Da principiante non ti servono ancora: ti basta sapere che /// è per la documentazione, mentre // è per le note normali. Quando sarai pronto, la pagina Documentazione ti mostra come scriverli, generare la documentazione e perfino trasformare gli esempi in test.

Pratica

1. Spegni una riga

Questo programma stampa tre righe. Trasforma la riga centrale in un commento in modo che vengano stampate solo Riga 1 e Riga 3. Suggerimento: metti // all’inizio della riga che vuoi spegnere.

fn main() {
    println!("Riga 1");
    println!("Riga 2");
    println!("Riga 3");
}

Mostra la soluzione

fn main() {
    println!("Riga 1");
    // println!("Riga 2");
    println!("Riga 3");
}

Output:

Riga 1
Riga 3

▶ Provalo tu

2. Spegni due righe in una volta

Ora stampa da Riga 1 a Riga 4, ma usa un unico commento a blocco per spegnere le righe 2 e 3. Suggerimento: apri il commento con /* prima della riga 2 e chiudilo con */ dopo la riga 3.

Mostra la soluzione

fn main() {
    println!("Riga 1");
    /*
    println!("Riga 2");
    println!("Riga 3");
    */
    println!("Riga 4");
}

Output:

Riga 1
Riga 4

▶ Provalo tu

Riepilogo

I commenti sono note che Rust ignora; usali per spiegare il tuo codice.
// apre un commento di riga (il tipo più comune).
/* ... */ è un commento a blocco per più righe, e i commenti a blocco si possono annidare.
I buoni commenti spiegano il perché, non quello che il codice dice già.
/// è un commento di documentazione, usato per generare la documentazione.

Verifica veloce

1. Cosa fa Rust con i commenti quando compila il tuo codice?

2. A cosa servono i commenti di documentazione ///?

Punteggio: 0 / 2

Per approfondire

Comments — The Rust Book (in inglese): la breve sezione ufficiale sui commenti // e su dove di solito si mettono.
Comments — Rust by Example (in inglese): tutti gli stili di commento in un unico esempio eseguibile, compresi i commenti a blocco dentro un’espressione.
Making Useful Documentation Comments — The Rust Book (in inglese): un primo sguardo a /// e //! e a come li usa cargo doc.
How to write documentation — The rustdoc book (in inglese): consigli su cosa deve contenere un buon commento di documentazione, per quando scriverai una libreria.
Comments — The Rust Reference (in inglese): le regole esatte, compresi i commenti a blocco annidati.