Comentarios en R: cómo comentar tu código (y comentar bloques)

El símbolo

Un comentario en R empieza con #. Desde ese carácter hasta el final de la línea, R lo ignora todo:

# 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)

Ambas ubicaciones son legales: un comentario en su propia línea, o un comentario en línea después del código. No hay nada que cerrar - el comentario simplemente termina donde termina la línea. Un solo # basta, y un # dentro de una cadena entre comillas es solo un carácter, no un comentario:

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

R no tiene comentario multilínea

Aquí está la respuesta a la pregunta que todo principiante de R acaba googleando: R no tiene sintaxis de comentario de bloque. No hay /* ... */, no hay """docstring""", no hay =begin/=end. Cada línea comentada necesita su propio #. Es una simplicidad deliberada del lenguaje - y es menos doloroso de lo que suena, porque las herramientas llenan el hueco.

La solución del mundo real: el atajo de alternar de tu editor. En RStudio, selecciona las líneas y pulsa Ctrl+Shift+C (Windows/Linux) o Cmd+Shift+C (macOS). Cada línea seleccionada recibe un prefijo #; púlsalo de nuevo y desaparecen. Esto es lo que los programadores de R hacen de verdad, docenas de veces al día, y vale la pena grabarlo en la memoria muscular esta misma semana. VS Code, Vim y Emacs tienen comandos equivalentes de alternar comentarios para archivos de R.

El truco de if (FALSE). Como FALSE nunca es verdadero, envolver código en if (FALSE) { ... } garantiza que nunca se ejecute:

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

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

Conócelo, pero trátalo como una curiosidad más que como un hábito, porque tiene advertencias reales. El código omitido debe seguir siendo R sintácticamente válido - un verdadero comentario de bloque puede contener cualquier cosa, pero un if (FALSE) alrededor de una línea a medio escribir es un error de parseo que detiene todo el script. También cambia de significado en silencio si las llaves se editan. Cuando quieras líneas desactivadas, el atajo del editor es más seguro; cuando las quieras fuera, bórralas - para eso está el control de versiones.

Qué dicen los buenos comentarios: el porqué, no el qué

El código ya dice lo que hace. Un comentario que lo repite es ruido que acabará quedándose desactualizado y empezará a mentir:

# 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

El segundo comentario aporta información que el código no puede: por qué existe el incremento. Esa es la prueba para cada comentario que escribas - ¿explica la intención, el contexto o una decisión no obvia? Los comentarios se ganan su sitio en las líneas raras: la solución alternativa para el bug de un paquete, el desfase de uno que es intencionado, la fórmula que salió de un artículo concreto. Y recuerda la regla de mantenimiento: cuando cambies el código, cambia su comentario, porque un comentario equivocado es peor que ninguno.

Si te encuentras escribiendo un comentario para explicar qué contiene una variable, a menudo la mejor solución es un nombre más claro - mira variables para ese argumento.

Encabezados de sección que se pliegan en RStudio

Los scripts de análisis se hacen largos, y los comentarios hacen de tabla de contenidos. RStudio trata una línea de comentario que termina en cuatro o más - (o = o #) como un encabezado de sección:

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

# Clean and reshape ----

# Model ====

Cada sección se vuelve plegable y aparece en el esquema del documento de RStudio, de modo que un script de 300 líneas se convierte en una lista navegable de pasos: cargar, limpiar, modelar, graficar. Cualquiera de los caracteres finales funciona siempre que haya al menos cuatro; elige un estilo y mantenlo consistente. Incluso fuera de RStudio, los comentarios de encabezado de sección hacen visible la estructura de un script de un vistazo - es la documentación más barata que un análisis puede tener.

Comentarios roxygen2: #' en su hábitat

Al leer código R de otras personas - especialmente el código fuente de paquetes - te encontrarás comentarios que empiezan 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
}

Estos son comentarios de documentación de roxygen2. Escritos directamente encima de la definición de una función, las herramientas de paquetes los compilan en las páginas de ayuda formales que lees con ?function_name. Las etiquetas (@param, @return) describen las entradas y la salida de la función. Para el propio R, una línea #' es un comentario ordinario - la convención solo tiene poder dentro de la cadena de herramientas de desarrollo de paquetes. No necesitas escribirlos hasta que construyas un paquete o documentes tus propias funciones en serio; por ahora, solo reconócelos para que el código fuente de los paquetes no parezca misterioso.

Lo que te llevas

• # inicia un comentario; llega hasta el final de la línea, tanto si la línea es todo comentario como si es código-y-luego-comentario.
• R no tiene comentario multilínea - alterna bloques con Ctrl/Cmd+Shift+C en RStudio, y reserva if (FALSE) {} para código sintácticamente válido que rara vez omites.
• Comenta el porqué, no el qué - y actualiza los comentarios cuando el código cambie.
• Los comentarios # Section name ---- dan a RStudio secciones plegables y dan a los lectores un mapa del script.
• Las líneas #' son comentarios de documentación de roxygen2 que se convierten en páginas de ayuda de paquetes.

Lo siguiente: las variables - crearlas con <-, nombrarlas bien y cómo trata R los valores que contienen.