Commenti in R
I commenti in R sono porzioni di testo che vengono ignorate dall’interprete e servono a documentare il codice, renderlo leggibile e facilitare la collaborazione tra programmatori. In R, il sistema di commenti è semplice ma efficace, e con l’ausilio di strumenti come roxygen2 è possibile generare documentazione professionale.
Commenti Singola Riga
In R, i commenti si creano con il simbolo #. Tutto ciò che segue il cancelletto sulla stessa riga viene ignorato dall’interprete:
# Questo è un commento su singola riga
x <- 10 # Assegna il valore 10 alla variabile x
# Calcolo della media
media <- mean(c(4, 8, 15, 16, 23))
print(media)
# [1] 13.2
Il simbolo # può essere posizionato all’inizio della riga per commentare l’intera riga, oppure dopo un’istruzione per aggiungere una nota esplicativa.
R Non Ha Commenti Multi-Riga Nativi
A differenza di linguaggi come C, Java o Python, R non dispone di una sintassi nativa per i commenti multi-riga. Non esiste un equivalente di /* ... */ o """ ... """. Per commentare più righe, è necessario inserire # all’inizio di ciascuna riga:
# Questa funzione calcola il BMI (Body Mass Index)
# a partire dal peso in chilogrammi
# e dall'altezza in metri
calcola_bmi <- function(peso, altezza) {
return(peso / altezza^2)
}
risultato <- calcola_bmi(75, 1.80)
print(risultato)
# [1] 23.14815
La maggior parte degli editor moderni come RStudio permette di commentare e decommentare rapidamente blocchi di codice selezionati tramite la scorciatoia Ctrl + Shift + C.
Best Practices per i Commenti
Scrivere buoni commenti è un’arte. Ecco alcune linee guida fondamentali:
# BUONO: spiega il "perché", non il "cosa"
# Filtriamo i valori anomali oltre 3 deviazioni standard
dati_puliti <- dati[abs(scale(dati)) < 3]
# CATTIVO: commento ridondante che ripete il codice
# Assegna 5 a x
x <- 5
# BUONO: separa le sezioni logiche del codice
# --- Caricamento dati ---
dati <- read.csv("dataset.csv")
# --- Pulizia dati ---
dati <- na.omit(dati)
# --- Analisi ---
summary(dati)
Alcuni consigli pratici:
- Spiega il perché, non il cosa: il codice stesso dice cosa fa, il commento dovrebbe spiegare la ragione
- Mantieni i commenti aggiornati: un commento obsoleto è peggio di nessun commento
- Usa commenti per separare sezioni: aiuta la leggibilitĂ nei script lunghi
- Evita commenti eccessivi: troppi commenti rendono il codice difficile da leggere
Documentazione con roxygen2
Per documentare le funzioni in modo professionale, R utilizza il pacchetto roxygen2 con una sintassi speciale basata su #' (cancelletto seguito da apostrofo):
#' Calcola l'Indice di Massa Corporea (BMI)
#'
#' Questa funzione calcola il BMI a partire dal peso
#' e dall'altezza di una persona.
#'
#' @param peso Peso della persona in chilogrammi
#' @param altezza Altezza della persona in metri
#' @return Il valore numerico del BMI
#' @examples
#' calcola_bmi(70, 1.75)
#' # [1] 22.85714
#' @export
calcola_bmi <- function(peso, altezza) {
if (altezza <= 0) stop("L'altezza deve essere positiva")
return(peso / altezza^2)
}
I tag principali di roxygen2 sono:
@param: descrive un parametro della funzione@return: descrive il valore restituito@examples: fornisce esempi d’uso@export: indica che la funzione deve essere esportata dal pacchetto
Questa documentazione viene poi convertita automaticamente in pagine di help consultabili con ?calcola_bmi.
Conclusione
Anche se R offre un solo tipo di commento con #, questo è sufficiente per documentare efficacemente il codice. L’uso di roxygen2 con la sintassi #' eleva la documentazione a un livello professionale, rendendo le funzioni facilmente comprensibili e generando automaticamente le pagine di aiuto. Scrivere commenti chiari e significativi è una pratica essenziale per mantenere il codice leggibile e collaborativo nel tempo.