# Clean Code: cómo escribir código limpio y mantenible

**Categoría:** Programación · **Nivel:** Intermedio · **Lectura:** 11 min
**Publicada:** 2026-07-28 · **Actualizada:** 2026-07-28 · **Autoría:** Underc0de
**Versión HTML (canónica):** https://underc0de.org/guias/programacion/clean-code-codigo-limpio-y-mantenible/

## Respuesta rápida

**Clean Code** (código limpio) es escribir de forma que otras personas —y tu yo futuro— puedan entender y modificar el código con facilidad. La premisa que lo justifica: el código **se lee muchas más veces de las que se escribe**, así que optimizar para la lectura ahorra muchísimo más de lo que cuesta. Las prácticas de mayor impacto son pocas: **nombres que expliquen** qué hace cada cosa (`diasDesdeElPedido`, no `d`); **funciones pequeñas** que hagan una sola cosa; **comentarios que expliquen el porqué**, no el qué (el código ya dice qué hace); y **consistencia** con el estilo del proyecto. Pero con una advertencia clave: son **guías, no dogmas**. Aplicar reglas al pie de la letra sin criterio —abstraer de más, dividir en funciones diminutas todo— produce código tan difícil de leer como el que se quería evitar. El objetivo no es cumplir reglas: es que el próximo que lo lea lo entienda rápido.

## Por qué importa la legibilidad

La intuición de quien empieza es que el buen código es el que *funciona*. Y es cierto que tiene que funcionar; pero eso es el mínimo, no la meta. El software vive años, cambia de manos, se corrige y se amplía. La mayor parte del tiempo de programar no se va en escribir código nuevo, sino en **leer y entender** el que ya existe para poder tocarlo sin romperlo.

> **La premisa que lo cambia todo**
>
> El código se **escribe una vez y se lee cientos**. Cada vez que alguien tiene que corregir un error, agregar una función o entender qué pasa, lee. Y ese «alguien» muchas veces sos **vos mismo dentro de seis meses**, sin recordar nada de lo que pensabas hoy. Escribir limpio no es adornar: es bajar el costo de todas esas lecturas futuras. Un código que se entiende rápido se corrige rápido y se rompe menos.

## Los nombres: la mitad del trabajo

Si solo se pudiera mejorar una cosa del código, serían los **nombres**. Un buen nombre convierte una línea críptica en una que se lee sola:

```javascript
// Difícil: hay que descifrar qué es cada cosa.
function c(p, d) { return p * 0.5 + d * 0.1; }

// Claro: el nombre explica, sin necesidad de comentario.
function calcularRecargoDeEnvio(pesoKg, distanciaKm) {
  return pesoKg * TARIFA_POR_KG + distanciaKm * TARIFA_POR_KM;
}
```

Las reglas de los nombres son simples: que **revelen la intención** (qué es o qué hace), que se puedan **pronunciar y buscar**, y que sean **consistentes** (si es `usuario` en un lado, que no sea `user` en otro). El costo de escribir un nombre largo se paga *una vez*; el de descifrar uno críptico, en *cada* lectura. Y un buen nombre suele volver innecesario el comentario que explicaría qué hace.

## Funciones pequeñas y con un propósito

La segunda práctica de mayor impacto: cada **función debería hacer una sola cosa**. Una función que valida datos, calcula un precio, guarda en la base y manda un correo es imposible de entender de un vistazo, difícil de probar y peligrosa de modificar, porque tocar una parte puede romper las otras.

Dividirla en funciones pequeñas con nombres claros hace que la función principal se lea como una lista de pasos:

```javascript
// La función principal se lee como lo que hace, en orden.
function procesarPedido(pedido) {
  validarPedido(pedido);
  const total = calcularTotal(pedido);
  guardarPedido(pedido, total);
  enviarConfirmacion(pedido);
}
```

Los beneficios son concretos: cada función se **entiende** sola, se **prueba** por separado (clave para el [testing](../../testing/testing-manual-desde-cero/index.md)), y se **reutiliza**. Esta separación también facilita la [depuración](../como-depurar-errores-de-programacion/index.md): cuando algo falla, se sabe en qué función mirar. La contracara —el equilibrio— es no exagerar, tema de la sección siguiente.

## Comentarios: el porqué, no el qué

Hay un malentendido extendido: que más comentarios es mejor código. No lo es. El mejor comentario suele ser el que **no hace falta** porque el código ya se explica solo. La regla que ordena esto: **comentá el *porqué*, no el *qué***.

```javascript
// Inútil: repite lo que el código ya dice.
i = i + 1;  // suma 1 a i

// Útil: explica un porqué que el código no puede expresar.
// Reintentamos 3 veces porque el proveedor de pagos
// devuelve un error transitorio en el primer intento.
reintentar(cobrar, 3);
```

El código dice *qué* hace; el comentario debe aportar lo que el código **no puede** decir: por qué se tomó una decisión rara, qué regla de negocio hay detrás, a qué problema conocido responde. Un comentario que repite el código además envejece mal: cuando el código cambia y el comentario no, miente. La documentación de referencia —como [MDN](https://developer.mozilla.org/es/)— es distinta: eso sí documenta el qué, para quien usa la función desde afuera.

## El equilibrio: guías, no dogmas

Esta sección es la que las guías entusiastas omiten y la que más importa. Las reglas del código limpio son **guías para un objetivo** —que se entienda—, no fines en sí mismas. Aplicadas sin criterio, producen el mismo daño que quieren evitar:

- **Sobreabstracción.** Crear capas, interfaces y funciones para «por si acaso» hace el código más difícil de seguir, no más limpio. La regla es resolver el problema que tenés, no el que imaginás.
- **Funciones diminutas de más.** Partir todo en funciones de una línea puede fragmentar la lógica tanto que haya que saltar entre veinte funciones para entender una operación. A veces una función de quince líneas legibles es mejor que cinco de tres.
- **Reglas por encima del contexto.** Cada proyecto y cada equipo tienen convenciones; la consistencia con ellas vale más que aplicar una regla de un libro.

> **Atención**
>
> Ante cualquier duda sobre si un cambio deja el código «más limpio», la pregunta es una sola: **¿la próxima persona que lea esto lo va a entender más rápido?** Si la respuesta es sí, es una mejora; si es «cumple la regla pero se entiende peor», no lo es. El objetivo nunca fue cumplir reglas: es la legibilidad. Los [patrones de diseño](../patrones-de-diseno-con-ejemplos-practicos/index.md) son un paso más en esta dirección, con la misma advertencia de no forzarlos.

## Errores frecuentes

- **Nombres crípticos.** Una letra o una abreviatura ahorran al escribir y cuestan en cada lectura. Que el nombre explique.
- **Funciones que hacen de todo.** Una función por responsabilidad se entiende, se prueba y se reutiliza mejor.
- **Comentar el qué.** Repetir lo que el código dice es ruido; comentá el porqué.
- **Comentarios que mienten.** Un comentario que no se actualizó con el código es peor que ninguno.
- **Sobreabstraer.** Capas y abstracciones «por si acaso» ensucian más de lo que limpian.
- **Aplicar reglas sin criterio.** El objetivo es la legibilidad, no cumplir una lista.
- **Ignorar el estilo del proyecto.** La consistencia con el equipo vale más que la preferencia personal.

## Preguntas frecuentes

**¿Por qué importa tanto la legibilidad si el código funciona?**
Porque que funcione es el mínimo, no la meta. El software vive años, cambia de manos y se corrige y amplía constantemente, y la mayor parte del tiempo de programar no se va en escribir código nuevo sino en leer y entender el que ya existe para poder modificarlo sin romperlo. La premisa central del código limpio es que el código se escribe una vez y se lee cientos de veces: cada corrección de un error, cada función que se agrega, cada intento de entender qué hace algo implica una lectura. Y muchas de esas lecturas las hará uno mismo meses después, sin recordar nada del razonamiento original. Escribir limpio no es adornar ni cumplir un capricho estético: es bajar el costo de todas esas lecturas futuras, y un código que se entiende rápido se corrige rápido y se rompe menos.

**¿Cuál es la práctica de código limpio con más impacto?**
Elegir buenos nombres. Si solo se pudiera mejorar una cosa del código, serían los nombres de las variables, las funciones y las clases, porque un buen nombre convierte una línea que habría que descifrar en una que se lee sola y vuelve innecesario el comentario que la explicaría. Las reglas son simples: que el nombre revele la intención, es decir qué es o qué hace la cosa; que se pueda pronunciar y buscar; y que sea consistente en todo el proyecto, sin llamar a lo mismo de dos maneras distintas en lugares distintos. La clave económica es que el costo de escribir un nombre descriptivo, aunque sea largo, se paga una sola vez al escribirlo, mientras que el costo de descifrar un nombre críptico de una letra o una abreviatura oscura se paga en cada una de las cientos de lecturas futuras del código.

**¿Cuántos comentarios debería poner?**
Menos de los que probablemente creés, y de otro tipo. Hay un malentendido extendido de que más comentarios significan mejor código, pero no es así: el mejor comentario suele ser el que no hace falta porque el código ya se explica solo gracias a buenos nombres y funciones claras. La regla que ordena esto es comentar el porqué, no el qué. Un comentario que repite lo que el código evidentemente hace es ruido inútil, y además envejece mal, porque cuando el código cambia y el comentario no, el comentario pasa a mentir, que es peor que no tenerlo. En cambio, un comentario que explica algo que el código no puede expresar por sí mismo —el motivo de una decisión poco obvia, una regla de negocio rara, la referencia a un problema conocido— es muy valioso, porque aporta contexto que se perdería.

**¿Qué significa que una función haga «una sola cosa»?**
Significa que tenga una única responsabilidad clara, en lugar de mezclar varias tareas distintas. Una función que valida datos, además calcula un precio, además guarda en la base de datos y además envía un correo hace cuatro cosas, y eso la vuelve difícil de entender de un vistazo, difícil de probar de forma aislada y peligrosa de modificar, porque cambiar una de esas tareas puede romper las otras sin querer. La solución es dividirla en varias funciones pequeñas, cada una con un nombre claro que haga una sola de esas tareas, coordinadas por una función principal que se lea como una lista ordenada de pasos. Los beneficios son concretos: cada función se entiende sola, se puede probar por separado, se reutiliza en otros lugares, y cuando algo falla se sabe con precisión en cuál mirar.

**¿El código limpio no es solo una cuestión de gustos?**
No, aunque tenga zonas grises. Hay principios con fundamento objetivo —nombres que revelan la intención, funciones con una sola responsabilidad, comentarios que aportan lo que el código no dice— que reducen de forma medible el tiempo y el riesgo de mantener el software, y eso no es cuestión de gusto sino de costo. Lo que sí tiene un componente de convención es el estilo concreto: la indentación, dónde van las llaves, ciertos nombres. En eso, más que una preferencia personal correcta, lo que importa es la consistencia dentro del proyecto y del equipo, porque un código consistente se lee mejor aunque el estilo elegido no sea el que uno preferiría. Así que hay una base objetiva sólida y una capa de convenciones donde lo valioso es acordar y respetar un estándar común.

**¿Se puede exagerar con el código limpio?**
Sí, y es un error tan común como el código descuidado. Las reglas del código limpio son guías para un objetivo —que el código se entienda— y no fines en sí mismas, así que aplicarlas al pie de la letra sin criterio produce el mismo daño que se quería evitar. La sobreabstracción es el ejemplo típico: crear capas, interfaces y estructuras «por si acaso» para problemas que no se tienen hace el código más difícil de seguir, no más limpio. Partir todo en funciones diminutas de una línea puede fragmentar la lógica tanto que haya que saltar entre decenas de funciones para entender una operación simple. La prueba definitiva ante cualquier cambio es una sola pregunta: ¿la próxima persona que lea esto lo va a entender más rápido? Si la respuesta es que cumple la regla pero se entiende peor, entonces no es una mejora.

## Fuentes

Documentación oficial y material de la comunidad consultados para esta guía. Fecha de consulta: 28 de julio de 2026.

### Aportes de la comunidad Underc0de

1. **Underc0de, foro.** [Sección Programación](https://underc0de.org/foro/programacion/). Discusiones sobre calidad de código, estilo y mantenibilidad.
2. **Underc0de, foro.** [Sección Desarrollo web](https://underc0de.org/foro/desarrollo-web/). Buenas prácticas en proyectos reales.

### Documentación oficial

1. **Martin Fowler.** [Refactoring](https://refactoring.com/). Referencia sobre cómo mejorar la estructura del código sin cambiar su comportamiento.
2. **Mozilla.** [Guía de estilo de código](https://developer.mozilla.org/es/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). Convenciones de legibilidad de referencia.
3. **The Twelve-Factor App.** [The Twelve-Factor App](https://12factor.net/es/). Principios de mantenibilidad para aplicaciones, incluida la gestión de la configuración.
4. **Refactoring Guru.** [Code smells](https://refactoring.guru/es/refactoring/smells). Catálogo de señales de código que conviene mejorar.

## Guías relacionadas

- [Ruta de estudio completa](../ruta-de-estudio-completa-para-aprender-a-programar/index.md)
- [Patrones de diseño](../patrones-de-diseno-con-ejemplos-practicos/index.md)
- [Depurar errores](../como-depurar-errores-de-programacion/index.md)
- [TypeScript desde cero](../typescript-desde-cero/index.md)
- [Índice de Programación](../index.md)