Comentarios en código

Los comentarios son notas que escribes dentro del código para personas. JavaScript las ignora por completo: no se ejecutan, no ocupan memoria en el resultado y no cambian el comportamiento del programa. Sirven para explicar decisiones, dejar recordatorios o desactivar temporalmente una línea.

Bien usados, hacen el código más fácil de entender. Mal usados, lo llenan de ruido.

Objetivos

Al terminar esta lección deberías ser capaz de:

Escribir comentarios de una línea y de varias líneas.
Usar comentarios para aclarar el porqué, no repetir el qué.
Conocer el formato JSDoc para documentar funciones.
Desactivar código temporalmente con comentarios.
Evitar los comentarios que estorban o quedan desactualizados.

Los dos tipos básicos

Comentario de una línea: `//`

Todo lo que va después de // en esa línea se ignora.

// Este programa calcula el total de una compra
const precio = 30;

const total = precio * 1.21; // Añadimos el IVA al final de la línea
console.log(total);

Puede ir ocupando la línea entera o al final de una instrucción.

Comentario de bloque: `/* ... */`

Sirve para varias líneas. Todo lo que haya entre /* y */ se ignora.

/*
  Calculamos el precio final.
  Por ahora el IVA es fijo; más adelante vendrá de la configuración.
*/
const precio = 30;
const iva = 0.21;
const total = precio + precio * iva;

También puede usarse en medio de una línea, aunque es menos habitual:

const total = precio /* base */ + precio * iva;

JSDoc: un formato especial

Existe un formato de bloque que empieza con /** en lugar de /*. Se llama JSDoc y se usa para dejar notas con etiquetas como @param y @returns. Muchos editores (como VS Code) lo leen y muestran la descripción al pasar el ratón por encima.

No lo desarrollaremos aquí: lo retomaremos en Funciones, que es donde tiene sentido usarlo. Por ahora basta con que sepas reconocer el /** inicial.

Comentarios que sí aportan: explica el PORQUÉ

La regla de oro es: el código ya dice qué hace; el comentario debe decir por qué se hizo así.

// ❌ Repite lo que ya se ve
// Suma 1 a i
i = i + 1;

// ✅ Explica una decisión que no se deduce del código
// Usamos 0.21 porque la tienda vende solo en España (IVA general).
const IVA = 0.21;

Casos en los que un comentario sí merece la pena:

Decisiones de negocio: “El pedido caduca a los 15 minutos por política de la tienda”.
Trucos poco obvios: “Redondeamos antes de comparar por el error de 0.1 + 0.2”.
Avisos: “No cambies el orden: la API exige este formato”.
Recordatorios: // TODO: validar que el correo no esté vacío.
Código temporalmente desactivado mientras pruebas algo.

// TODO: sustituir este valor fijo por una llamada a la API
const DESCUENTO = 5;

// El servidor devuelve los decimales como texto, por eso convertimos.
const precio = Number(datos.precio);

Comentarios que estorban

Mal hábito	Por qué molesta	Mejor alternativa
Repetir lo obvio (`// crea variable`)	Añade ruido sin información	Bórralo
Comentarios desactualizados	Mienten y confunden	Actualízalos o elimínalos
Dejar código viejo “por si acaso”	Ensucia el archivo	Bórralo; para eso está el control de versiones (Git)
Comentar cada línea	Hace el código ilegible	Agrupa y explica solo lo importante
Usar comentarios en vez de buenos nombres	`// guarda la edad` + `let e`	Renombra a `let edadUsuario`

// ❌ Con comentarios que no aportan
// Guardamos la e
const e = 28;
// Comprobamos si es mayor
if (e > 18) {
  // Mostramos mensaje
  console.log("ok");
}

// ✅ Sin comentarios, con nombres claros
const edadUsuario = 28;

if (edadUsuario > 18) {
  console.log("Acceso permitido");
}

Desactivar código temporalmente

Mientras pruebas, puedes “apagar” líneas sin borrarlas:

console.log("Versión A");
// console.log("Versión B"); // temporalmente desactivada
console.log("Versión C");

Para varias líneas, /* */ es más rápido:

/*
console.log("Bloque de pruebas");
console.log("Que aún no quiero ejecutar");
*/

Muchos editores permiten hacerlo con un atajo (Ctrl + / o Cmd + /) que convierte la selección en comentarios de una línea y viceversa.

Lo que NO son los comentarios

No son una forma de ocultar contraseñas: el código fuente se puede leer igual.
No corrigen un código confuso: si hace falta mucho texto para explicar tres líneas, probablemente haya que reescribirlas.
No afectan al rendimiento: el motor de JavaScript los descarta; puedes escribir los que necesites sin miedo.
No funcionan dentro de un texto: "esto // no es un comentario" es simplemente parte del string.

const url = "https://ejemplo.com"; // ✅ comentario real
const texto = "https://ejemplo.com"; // las // van dentro de las comillas: son texto

Resumen de sintaxis

Tipo	Sintaxis	Uso típico
Una línea	`// nota`	Aclaraciones cortas, `TODO`, desactivar una línea
Bloque	`/* nota */`	Explicaciones largas, desactivar varias líneas
JSDoc	`/** ... @param ... */`	Bloque especial que se verá en Funciones

Errores frecuentes

Escribir // dentro de una cadena de texto pensando que comenta.
Anidar /* */ dentro de otro /* */.
Dejar comentarios que ya no coinciden con el código.
Comentar cada línea en lugar de usar nombres descriptivos.
Acumular código viejo comentado “por si hace falta”.
Olvidar cerrar un */, lo que convierte el resto del archivo en comentario.

Ejercicio

Escribe un programa de 5 líneas con un comentario de una línea y otro de bloque.
Busca en ese programa un comentario que solo repita lo que hace el código y bórralo; sustitúyelo por un nombre de variable mejor.
Escribe un bloque /* ... */ de tres líneas explicando por qué elegiste cierto valor.
Desactiva dos líneas con // y comprueba que el programa sigue funcionando.

Resumen

JavaScript ignora los comentarios: son notas para personas.
// comenta una línea; /* ... */ comenta un bloque; /** ... */ es el formato JSDoc que veremos en Funciones.
Comenta el porqué, no el qué: el código ya explica qué hace.
Un buen nombre de variable suele ser mejor que un comentario.
Usa TODO, FIXME y comentarios temporales, pero borra el código muerto al terminar.
Los comentarios no afectan al rendimiento ni sirven para ocultar datos sensibles.

Siguiente paso: Funciones.