Comentarios en JavaScript: escribir código que se explica solo

Publicado: 03/12/2025 Por: Juan Felipe Orozco Cortés
📚 Contenido de la guía ⌃

¿Has abierto un archivo JavaScript y has pensado: “este código funciona… pero no entiendo nada”? A veces el problema no es el lenguaje, sino cómo nos hablamos a nosotros mismos en el código: comentarios que no dicen nada, comentarios desactualizados o, peor, archivos enteros sin una sola pista de intención.

En esta guía vamos a ver cómo usar los comentarios en JavaScript para escribir código que se explica solo. No se trata de llenar todo de texto, sino de aprender cuándo comentar, qué comentar y cómo para que tu yo del futuro (o tu compañero de equipo) puedan entender decisiones, atajos y rarezas sin sufrir.

La idea no es memorizar tipos de comentario, sino construir un criterio profesional: qué hace que un comentario sea útil, qué huele mal y cómo apoyarte en comentarios + buenos nombres + pequeñas funciones para que tu código sea una historia clara.

1. El mapa mental de los comentarios en JavaScript 🧠

Antes de ver sintaxis, pensemos en para qué existe un comentario. En un proyecto real, casi todos los comentarios caen en una de estas cuatro categorías:

  • Explicar intención: qué está intentando lograr este bloque (el “para qué”).
  • Explicar contexto: por qué se tomó una decisión rara o distinta a lo obvio.
  • Explicar contrato: qué espera una función (inputs, outputs, errores).
  • Ruido / basura: cosas que el código ya dice o que se quedaron obsoletas.

En esta guía vamos a empujar tus comentarios hacia los tres primeros tipos y a detectar rápido el cuarto. La meta: que cada comentario agregado pague su alquiler en claridad.

Cómo pensar los comentarios en JS

Intención Cuenta qué objetivo tiene el bloque (“validar pago antes de crear factura”).
Contexto Explica decisiones raras (“no usamos fetch por bug en navegador X”).
Contrato Define qué entra, qué sale y qué errores pueden lanzarse.
Ruido Repite lo obvio (“contador++ // suma 1 al contador”). Esto es lo que queremos evitar.
Figura 1: Un buen comentario no describe lo que ya se ve, sino lo que no se ve a simple vista.

2. Buenos vs malos comentarios: olfato de “código que se explica solo”

Antes de escribir nuevos comentarios, vale la pena entrenar el olfato. Mira estos ejemplos:

Ejemplo 1: comentario que no aporta nada

// suma 1 al contador
contador = contador + 1;

Este comentario es ruido. El código ya lo dice. Si mañana cambias la línea y te olvidas de actualizar el comentario, ahora tendrás código contradictorio.

Ejemplo 2: comentario que sí agrega intención

// avanzamos al siguiente intento de login fallido para bloquear después de 3
failedLoginAttempts += 1;

Aquí el comentario no explica “qué hace” la suma, sino para qué existe el contador: bloquear tras 3 intentos. Es una pista de negocio, no una traducción de sintaxis.

❌ Huele mal cuando: el comentario repite la línea, traduce palabra por palabra o se queda desactualizado tras un refactor.

✅ Huele bien cuando: el comentario cuenta historia, contexto o reglas de negocio que el código por sí solo no revela.

3. Comentarios de intención: contar el “para qué”, no el “cómo”

El tipo más valioso de comentario es el que responde a la pregunta: “¿qué está intentando lograr este bloque?”. El código ya se encarga del cómo; el comentario cuenta el por qué.

Ejemplo: intención clara en una función de pago

// Validamos que el usuario pueda pagar ANTES de llamar a la pasarela externa
function canProcessPayment(user, cartTotal) {
  const hasValidEmail = Boolean(user.email);
  const hasPositiveBalance = cartTotal > 0;
  const isAccountActive = user.status === 'active';

  return hasValidEmail && hasPositiveBalance && isAccountActive;
}

La función ya tiene buen nombre, pero el comentario encima marca una decisión importante: validar antes de llamar a un servicio externo. Esa decisión ahorra dinero, tiempo y problemas de soporte.

Mini-refactor: cuando un comentario de intención te pide una función

// calcula si el usuario puede pagar
const canPay = user.balance >= cartTotal && !user.isBlocked;

Si tu comentario se parece demasiado al nombre de una posible función, es una señal para extraerla: 

function canUserPay(user, cartTotal) {
  return user.balance >= cartTotal && !user.isBlocked;
}

const canPay = canUserPay(user, cartTotal);

Ahora tu código se explica mejor solo, y el comentario puede desaparecer sin perder claridad.

4. Comentarios de contexto: justificar decisiones raras

A veces el código es raro a propósito: se usa una solución menos elegante para hacer feliz a un navegador viejo, una API externa o un bug conocido. Ahí un comentario de contexto es oro puro.

Ejemplo: explicando un “hack” controlado

// ⚠️ No usamos fetch aquí porque el navegador del laboratorio (IE11) no lo soporta.
// Esta ruta se eliminará cuando se actualicen los equipos (ticket #1234).
function legacyPost(url, data, callback) {
  const xhr = new XMLHttpRequest();
  xhr.open('POST', url);
  xhr.onreadystatechange = () => {
    if (xhr.readyState === 4) callback(xhr.status, xhr.responseText);
  };
  xhr.send(JSON.stringify(data));
}

Sin ese comentario, alguien podría “mejorar” el código reemplazándolo por fetch y romper un laboratorio entero sin saber por qué.

5. Comentarios de contrato: JSDoc para funciones que importan

Para funciones centrales (servicios, utilidades compartidas, lógica de negocio), vale la pena usar un formato más estructurado como JSDoc. Eso permite que VS Code y otros editores te muestren ayuda al escribir.

Ejemplo de función documentada con JSDoc

/**
 * Calcula el promedio de notas de un estudiante.
 *
 * @param {number[]} grades - Lista de notas entre 0.0 y 5.0.
 * @returns {{ average: number, status: 'aprobado' | 'reprobado' }}
 *   average  Promedio numérico.
 *   status   Estado final según la nota mínima institucional (3.0).
 */
function calculateGradeStatus(grades) {
  if (!grades.length) {
    return { average: 0, status: 'reprobado' };
  }

  const sum = grades.reduce((acc, grade) => acc + grade, 0);
  const average = sum / grades.length;
  const status = average >= 3 ? 'aprobado' : 'reprobado';

  return { average, status };
}

Aquí el comentario actúa como mini documentación: explica rangos, retorno y decisión de negocio (nota mínima 3.0). Eso no se ve directamente en el código, pero afecta reglas del colegio.

Verde ✅

Explica intención, contexto o contrato. No repite lo obvio. Se siente atado a reglas de negocio.

Amarillo ⚠️

Describe el “cómo”. Útil solo si el algoritmo es complejo. Revisa si puedes extraer funciones con buen nombre.

Rojo 🛑

Duplican el código, están desactualizados o son chistes internos que nadie entiende. Son los primeros en salir.

Estás viendo solo el 60% del contenido. ¡Únete a la Membresía Premium! para acceder al contenido completo.

← Volver a Guías

Comentarios y Valoraciones

No hay comentarios aún. ¡Sé el primero en opinar!

Por favor espere...