Rubén Tejera

Nivel inicial8 min de lectura · Publicado el

Comentarios en código limpio: cuándo sí y cuándo no

Comentarios en código limpio: una nota en la nevera dice «queda leche», pero la nevera está vacía; el código es lo único que dice la verdad. Un comentario puede mentirrubentejera.com quedalechela nota:el comentariola nevera:el código
La nota dice «queda leche», pero alguien se la acabó y nadie quitó la nota. La nevera es el código, lo único que dice la verdad; el comentario se queda sin actualizar y miente.

Abres un fichero y encuentras un comentario que dice una cosa y un código que hace otra. ¿A quién haces caso? Al código, porque es lo único que se ejecuta.

Un comentario es como una nota pegada en la nevera que dice «queda leche». Cuando alguien se acaba la leche, nadie quita la nota. El código cambia cada semana; los comentarios, casi nunca. Por eso, cuanto más se apoya un programa en comentarios para entenderse, más fácil es que mienta.

Este artículo se basa en el capítulo 4, «Comments», del libro Clean Code de Robert C. Martin, resumido con palabras propias y con ejemplos nuevos. La idea central del capítulo es que un comentario suele ser la señal de que no hemos sabido expresarnos con el código. No está prohibido usarlos, pero tampoco hay nada que celebrar cuando hacen falta.

El código es lo único que no miente: es lo que se ejecuta.

Por qué los comentarios no arreglan un código confuso

  • Solo el código cuenta lo que pasa de verdad. Es la única fuente de información precisa.
  • Mantener comentarios cuesta. Cada vez que cambias el código, tendrías que revisar el comentario. En la práctica, se olvida.
  • Un comentario no aclara un código enrevesado. Un código claro y casi sin comentarios es mucho mejor que uno complejo y lleno de explicaciones.

La energía que gastarías en escribir y mantener comentarios rinde más si la dedicas a que el código sea descriptivo y claro.

No uses un comentario: usa una función o una variable

Muchas veces basta con crear una función o una variable cuyo nombre diga lo mismo que el comentario que ibas a escribir.

Antes, el comentario explica la condición:

export function calcularEnvio(pedido) {
  // envío gratis si el cliente es premium o el pedido llega a 50 €
  if (pedido.cliente.tipo === 'premium' || pedido.total >= 50) {
    return 0;
  }
  return 4.95;
}

Después, los nombres explican la condición y el comentario sobra:

const PEDIDO_MINIMO_ENVIO_GRATIS = 50;
const COSTE_ENVIO = 4.95;

function tieneEnvioGratis(pedido) {
  const esPremium = pedido.cliente.tipo === 'premium';
  const llegaAlMinimo = pedido.total >= PEDIDO_MINIMO_ENVIO_GRATIS;
  return esPremium || llegaAlMinimo;
}

export function calcularEnvio(pedido) {
  return tieneEnvioGratis(pedido) ? 0 : COSTE_ENVIO;
}

Si mañana el mínimo pasa a 60 €, cambias una constante y el código sigue diciendo la verdad. Con la versión de antes, lo normal es que alguien cambie el 50 y el comentario se quede diciendo 50 €.

Para cambiar código con tranquilidad, primero asegúrate de que hace lo mismo. Este test comprueba que las dos versiones devuelven lo mismo en los casos importantes, incluido el límite de 50 €:

import { test } from 'node:test';
import assert from 'node:assert/strict';
import * as antes from './antes.js';
import * as despues from './despues.js';

const casos = [
  { cliente: { tipo: 'premium' }, total: 10, esperado: 0 },
  { cliente: { tipo: 'normal' }, total: 50, esperado: 0 },
  { cliente: { tipo: 'normal' }, total: 49.99, esperado: 4.95 },
];

for (const version of [antes, despues]) {
  test(`calcularEnvio (${version === antes ? 'antes' : 'después'})`, () => {
    for (const { esperado, ...pedido } of casos) {
      assert.equal(version.calcularEnvio(pedido), esperado);
    }
  });
}
node --test
# ✔ calcularEnvio (antes)
# ✔ calcularEnvio (después)

Si quieres profundizar en cómo elegir esos nombres, sigue con Nombres con sentido.

Comentarios que sí merecen la pena

Suelen aportar

  • Por qué se decidió así
  • Avisos de consecuencias
  • Destacar algo que parece irrelevante
  • Avisos legales y documentación de una API pública

Suelen sobrar

  • Repetir lo que hace el código
  • Marcar dónde se cierra una llave
  • Código comentado
  • Historia del fichero o información de otro sitio

Explicar la intención

El código cuenta qué hace; a veces hace falta contar por qué se eligió esa solución y no otra:

// Sumamos en céntimos: con decimales, 0.1 + 0.2 da 0.30000000000000004.
const totalEnCentimos = lineas.reduce((suma, linea) => suma + linea.precioEnCentimos, 0);

Sin el comentario, alguien podría «simplificarlo» a decimales y meter un error de redondeo. Cuando el porqué no es de una línea sino de una decisión de diseño entera, su sitio es un ADR.

Advertir de las consecuencias

Avisa a quien venga después de lo que puede pasar si toca algo. Por ejemplo: // No lo ejecutes en los tests: tarda varios minutos y llama a un servicio real.

Amplificar

Sirve para destacar la importancia de algo que, de otro modo, parecería irrelevante. Por ejemplo, un trim() que parece de adorno pero evita que un espacio al final rompa la búsqueda.

Avisos legales y documentación pública

Las cabeceras de licencia y la documentación de una API pública (JSDoc, Javadoc) son comentarios útiles, siempre que se mantengan al día. Dentro del código interno, documentar cada función por obligación suele convertirse en ruido.

Comentarios que conviene evitar

Comentarios al cerrar estructuras

Los comentarios al cerrar una llave para indicar qué bloque termina (} // fin del for) suelen aparecer en funciones muy largas. Si los necesitas, prueba a reducir el tamaño de la función. Hay más ideas en Funciones, código limpio.

Fragmentos de código comentado

No dejes código comentado. Quien lo vea no se atreverá a borrarlo: pensará que está ahí por algo y que es demasiado importante para quitarlo. Así se acumula durante años.

Bórralo sin miedo: si usas Git, el historial lo guarda. Para encontrar cuándo desapareció un fragmento, busca un texto que contenía:

git log -S "4.95" -p -- envio.js

-S muestra los commits en los que ese texto aparece o desaparece, y -p enseña el cambio.

Información fuera de contexto

Si escribes un comentario, que hable del código que tiene al lado. No pongas información global del sistema (la configuración de otro servicio, un puerto por defecto que se define en otro fichero) en un comentario local: cuando eso cambie, nadie se acordará de este comentario.

Información superflua

No incluyas reflexiones históricas, debates de cómo se llegó hasta aquí ni descripciones de detalles irrelevantes. Para la historia ya están los mensajes de los commits y las peticiones de cambio.

Comentarios TODO

Un TODO marca algo que crees que habría que hacer y que, por ahora, no se puede o no se ha hecho. Por ejemplo:

  • Un recordatorio para eliminar una función obsoleta.
  • Una petición para buscar un nombre más adecuado.
  • Un cambio que depende de algo previsto, como la nueva versión de una librería.

Son aceptables, pero no son excusa para dejar código malo. Revísalos de vez en cuando y elimina todos los que puedas. Si un TODO va a durar, mejor convertirlo en una tarea del equipo y dejar en el comentario su referencia.

Muchos IDE los localizan por ti. En IntelliJ IDEA, la ventana View | Tool Windows | TODO lista todos los comentarios TODO y FIXME del proyecto, y puedes añadir tus propios patrones.

Comentarios y código generado con IA

Los asistentes de IA tienden a llenar el código de comentarios que repiten lo que hace cada línea («incrementa el contador»). Son la nota de la nevera multiplicada por cien: dentro de unos cambios, ya no dirán la verdad.

Como criterio del enfoque IA Limpia, el código generado se revisa igual que el escrito a mano: se quitan los comentarios que repiten el código, se sustituyen por nombres claros y se conservan solo los que explican el porqué. También puedes pedírselo al agente en sus instrucciones, pero la revisión final sigue siendo tuya.

Tu lista de comprobación

  1. ¿Puedo decirlo con el nombre de una función o de una variable? Entonces, sin comentario.
  2. ¿El comentario explica por qué, avisa de algo o destaca algo importante? Entonces, déjalo.
  3. ¿Repite lo que hace el código, cierra una llave o cuenta historia? Bórralo.
  4. ¿Hay código comentado? Bórralo: está en Git.
  5. ¿Quedan TODO viejos? Resuélvelos o conviértelos en tareas.

Fuentes

  • Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship (Prentice Hall, 2008), capítulo 4, «Comments». Las ideas se resumen con palabras propias; no hay citas literales. Los ejemplos de código son nuevos, no del libro.
  • Documentación de IntelliJ IDEA 2026.3 sobre TODO, comprobada en noviembre de 2026: ventana View | Tool Windows | TODO y patrones TODO y FIXME por defecto.
  • Documentación de git log, opciones -S y -p.
  • Ejecutado en noviembre de 2026: el ejemplo de envío y su test con node:test en Node.js 24.21.0; el ejemplo de los céntimos en Node.js 24.21.0; git log -S con Git 2.53.0 en un repositorio de prueba.