Comentarios en JavaScript

Introducción

Este capítulo cubre todo lo que necesitas para escribir buenos comentarios en JavaScript: las dos sintaxis de comentarios (// comentarios de línea y /* */ comentarios de bloque), los doc-comentarios JSDoc para documentar funciones, la diferencia entre comentarios útiles y perjudiciales, y cómo comentar código durante la depuración. Los comentarios son texto que el motor de JavaScript ignora por completo durante la ejecución — existen únicamente para los humanos. Explican tu código a cualquiera que lo lea después, incluido tu yo futuro y tus compañeros de equipo. Como se eliminan antes de la ejecución, los comentarios no tienen ningún coste en tiempo de ejecución. (Una directiva relacionada que el motor sí lee es "use strict"; aunque parece una cadena al principio de un archivo, cambia cómo se ejecuta el código — consulta el capítulo sobre el modo estricto.)

Por qué comentar es esencial en JavaScript

Comentar puede parecer secundario, pero desempeña un papel fundamental en la programación. Ayuda a:

• Documentación del código: Para explicar la lógica compleja o el razonamiento detrás de ciertos segmentos de código.
• Legibilidad del código: Mejorar la comprensión del flujo y la funcionalidad del código.
• Depuración: Habilitar o deshabilitar fácilmente partes del código durante las pruebas o la depuración.
• Colaboración en equipo: Ayudar a otros desarrolladores a entender tu proceso de pensamiento.

Tipos de comentarios en JavaScript

JavaScript admite dos tipos principales de comentarios:

Comentarios de una sola línea

Los comentarios de una sola línea comienzan con // y se extienden hasta el final de la línea actual. Todo lo que aparece después de // en esa línea se ignora. Pueden estar en su propia línea o al final de una línea de código (un comentario en línea):

// This whole line is a comment
let a = 5, b = 10;

let sum = a + b; // inline comment: add the two values

Como un comentario // solo llega hasta el final de la línea, la siguiente línea vuelve a ser código normal — no necesitas "cerrarlo".

Comentarios multilínea

Los comentarios multilínea (también llamados comentarios de bloque) comienzan con /* y terminan con */. Todo lo que hay entre ellos se ignora, incluso a lo largo de muchas líneas. Úsalos para explicaciones más largas:

/*
  Returns the sum of two numbers.
  Both arguments are expected to be numbers;
  passing strings will concatenate instead of add.
*/
function add(a, b) {
    return a + b;
}

También puedes usar la sintaxis de bloque en medio de una línea, por ejemplo para etiquetar un argumento: setTimeout(run, 1000 /* ms */).

Atención — los comentarios de bloque no se anidan. Un */ termina el comentario en la primera ocurrencia, por lo que envolver código que ya contiene /* ... */ en otro comentario de bloque falla. El */ interno cierra el comentario antes de tiempo y el resto se convierte en código activo:

/*
  /* inner */
  alert('this still runs!');
*/

Copiar

Para comentar una región que contiene comentarios de bloque, usa // en cada línea en su lugar.

Comentarios buenos vs. malos: explica el por qué, no el qué

La regla más útil: comenta el por qué, no el qué. El código ya dice qué hace; un buen comentario captura la intención, la compensación o la restricción sorprendente que el código no puede expresar por sí solo.

// Bad: just restates the code — adds noise, can go stale
let total = 0; // set total to 0

// Good: explains a non-obvious constraint
const RETRY_LIMIT = 3; // the payment API rejects bursts above 3 calls/sec

Prefiere el código autodocumentado a los comentarios cuando sea posible. Una variable bien nombrada o una función pequeña a menudo elimina la necesidad de un comentario por completo:

// Needs a comment because the intent is hidden:
if (u.a && Date.now() - u.l < 86400000) { /* active in last 24h */ }

// No comment needed — the names say it:
const isActive = user.isVerified && wasSeenInLast24Hours(user);
if (isActive) {
  // ...
}

Algunas pautas adicionales:

1. Mantenlos actualizados. Un comentario que contradice el código es peor que ningún comentario — los lectores no pueden saber en cuál confiar.
2. Sé conciso. Explica el razonamiento, no cada paso.
3. No dejes código muerto comentado permanentemente. Elimínalo; el control de versiones lo recuerda.

Comentar código

Durante la depuración, a menudo quieres deshabilitar una línea o un bloque sin eliminarlo. Precede una línea con //, o envuelve una región en /* */:

let value = compute();
// console.log('Debug:', value); // temporarily silenced

/*
expensiveLogging(value);
sendToAnalytics(value);
*/

Esto es ideal para aislar qué parte del código causa un problema. Muchos editores permiten hacer esto con un atajo de teclado. Consulta el capítulo de la Console API para ver alternativas más limpias a los console.log de depuración que se quedan en el código.

Marcadores TODO y FIXME

Una convención habitual es etiquetar el trabajo inacabado con TODO (algo que hacer más adelante) o FIXME (un error conocido). Los editores y linters pueden listarlos automáticamente:

// TODO: optimize this loop for large data sets
// FIXME: breaks when input is an empty array

JSDoc: documentar funciones

JSDoc es un estándar para documentar funciones mediante un comentario de bloque especial que abre con /** (dos asteriscos). Etiquetas como @param y @returns describen las entradas y la salida. Las herramientas y los editores las leen para mostrar sugerencias en línea y generar documentación HTML.

/**
 * Adds two numbers together.
 * @param {number} a - The first addend.
 * @param {number} b - The second addend.
 * @returns {number} The sum of a and b.
 */
function add(a, b) {
    return a + b;
}

console.log(add(2, 3)); // 5

JSDoc se combina especialmente bien con las funciones: documentar los parámetros y los tipos de retorno deja claro el contrato de una función sin necesidad de leer su cuerpo. Otras etiquetas comunes son @throws, @example y @deprecated.

Conclusión

Incorporar comentarios efectivos en JavaScript no es solo una práctica de codificación, sino una habilidad de comunicación. Contribuye de manera significativa a la mantenibilidad y escalabilidad del código. Al dominar los comentarios en JavaScript, no solo mejoras tu código, sino que también potencias tu colaboración con otros en el proceso de desarrollo.

Recuerda que un código bien comentado es el reflejo de un desarrollador reflexivo y profesional. Aprovecha el poder de los comentarios y observa cómo tu código JavaScript se transforma en un recurso más accesible y mantenible.

Práctica