Commenti in R: come commentare il codice (e interi blocchi)

Il simbolo

Un commento in R inizia con #. Da quel carattere alla fine della riga, R ignora tutto:

# This whole line is a comment. R skips it.
speed_kmh <- 90

speed_ms <- speed_kmh / 3.6  # convert to meters per second

print(speed_ms)

Entrambe le posizioni sono valide: un commento su una riga a sé, oppure un commento in linea dopo il codice. Non c'è niente da chiudere: il commento finisce semplicemente dove finisce la riga. Basta un solo #, e un # dentro una stringa tra virgolette è solo un carattere, non un commento:

tag <- "#1 fan"  # the first # is data, this one is a comment
print(tag)

R non ha il commento multilinea

Ecco la risposta alla domanda che prima o poi ogni principiante di R cerca su Google: R non ha una sintassi per i commenti a blocchi. Non esiste /* ... */, non esiste """docstring""", non esiste =begin/=end. Ogni riga commentata ha bisogno del suo #. È una semplicità voluta del linguaggio, e fa meno male di quanto sembri, perché gli strumenti colmano la lacuna.

La soluzione pratica: la scorciatoia del tuo editor. In RStudio, seleziona le righe e premi Ctrl+Shift+C (Windows/Linux) o Cmd+Shift+C (macOS). Ogni riga selezionata riceve un # davanti; premi di nuovo e spariscono. È quello che i programmatori R fanno davvero, decine di volte al giorno, e vale la pena memorizzarla già questa settimana. VS Code, Vim ed Emacs hanno tutti comandi equivalenti per attivare e disattivare i commenti nei file R.

Il trucco di if (FALSE). Dato che FALSE non è mai vero, racchiudere il codice in if (FALSE) { ... } garantisce che non venga mai eseguito:

if (FALSE) {
    expensive_call <- 1 / 0
    cat("you will never see this\n")
}

cat("but you will see this\n")

Conoscilo, ma consideralo una curiosità più che un'abitudine, perché ha dei limiti concreti. Il codice saltato deve comunque essere R sintatticamente valido: un vero commento a blocchi può contenere qualsiasi cosa, mentre un if (FALSE) attorno a una riga scritta a metà è un errore di parsing che blocca tutto lo script. In più cambia significato in silenzio se qualcuno modifica le graffe. Quando vuoi disattivare delle righe, la scorciatoia dell'editor è più sicura; quando vuoi eliminarle, cancellale: il controllo di versione serve proprio a questo.

Cosa dicono i buoni commenti: il perché, non il cosa

Il codice dice già cosa fa. Un commento che lo ripete è rumore, che prima o poi resterà indietro rispetto al codice e comincerà a mentire:

# Bad: narrates the obvious
x <- x + 1  # add 1 to x

# Good: explains the reason
x <- x + 1  # customer-facing IDs are 1-based, data is 0-based

Il secondo commento porta un'informazione che il codice non può dare: perché esiste l'incremento. È il test da fare su ogni commento che scrivi: spiega l'intenzione, il contesto o una decisione non ovvia? I commenti si guadagnano il posto sulle righe strane: il workaround per il bug di un pacchetto, lo scarto di uno voluto, la formula presa da un articolo preciso. E ricorda la regola della manutenzione: quando cambi il codice, cambia anche il suo commento, perché un commento sbagliato è peggio di nessun commento.

Se ti ritrovi a scrivere un commento per spiegare cosa contiene una variabile, spesso la soluzione migliore è un nome più chiaro: trovi il ragionamento completo in variabili.

Intestazioni di sezione richiudibili in RStudio

Gli script di analisi diventano lunghi, e i commenti fanno anche da indice. RStudio tratta una riga di commento che termina con quattro o più - (oppure = o #) come un'intestazione di sezione:

# Load data ----------------------------------------------------------

# Clean and reshape ----

# Model ====

Ogni sezione diventa richiudibile e compare nella struttura del documento di RStudio, così uno script di 300 righe si trasforma in un elenco navigabile di passaggi: caricare, pulire, modellare, disegnare i grafici. Va bene qualsiasi carattere finale, purché siano almeno quattro; scegli uno stile e mantienilo coerente. Anche fuori da RStudio, i commenti usati come intestazioni rendono visibile la struttura di uno script a colpo d'occhio: è la documentazione più economica che un'analisi possa avere.

Commenti roxygen2: #' nel mondo reale

Leggendo il codice R di altre persone, soprattutto il sorgente dei pacchetti, incontrerai commenti che iniziano con #':

#' Convert a speed from km/h to m/s
#'
#' @param kmh Speed in kilometers per hour.
#' @return Speed in meters per second.
kmh_to_ms <- function(kmh) {
    kmh / 3.6
}

Sono commenti di documentazione roxygen2. Scritti subito sopra la definizione di una funzione, gli strumenti dei pacchetti li compilano nelle pagine di aiuto ufficiali che leggi con ?function_name. I tag (@param, @return) descrivono gli input e l'output della funzione. Per R stesso una riga #' è un normale commento: la convenzione ha effetto solo dentro gli strumenti di sviluppo dei pacchetti. Non ti serve scriverli finché non crei un pacchetto o non documenti sul serio le tue funzioni; per ora ti basta riconoscerli, così il sorgente dei pacchetti non ti sembrerà misterioso.

Cosa ti porti a casa

• # inizia un commento, che arriva fino alla fine della riga, sia che la riga sia tutta commento sia che contenga prima codice e poi un commento.
• R non ha il commento multilinea: commenta i blocchi con Ctrl/Cmd+Shift+C in RStudio e riserva if (FALSE) {} al codice sintatticamente valido che salti di rado.
• Commenta il perché, non il cosa, e aggiorna i commenti quando cambia il codice.
• I commenti # Section name ---- danno a RStudio sezioni richiudibili e ai lettori una mappa dello script.
• Le righe #' sono commenti di documentazione roxygen2 che diventano pagine di aiuto dei pacchetti.

Prossimo passo: le variabili, cioè come crearle con <-, come dare loro buoni nomi e come R tratta i valori che contengono.