Clean Code explicado sin gurús (qué principios sí importan)
Introducción
“Clean Code” se ha convertido en una palabra comodín. Se usa para justificar cambios útiles… y también para justificar refactors por estética, discusiones eternas en PRs y reescrituras que no mejoran nada.
Vamos a decirlo claro: en proyectos reales, Clean Code no es “código bonito”. Es código que reduce el coste de cambio. Si tu “código limpio” no reduce bugs, no mejora onboarding, no hace más fácil testear y no permite cambiar requisitos sin pánico, no es Clean Code: es postureo.
Qué es Clean Code en una frase útil
Escribir para humanos futuros: que otra persona pueda entender y modificar el sistema sin romperlo, con el mínimo contexto posible y con el máximo control de daños.
Clean Code no es una lista de reglas
La mayoría de guerras en equipos vienen de confundir principios con dogmas. Ejemplos de dogmas comunes: “funciones siempre de una línea”, “cero comentarios”, “nunca if”, “todo debe ser inmutable”, “todo debe ser abstracto”. Eso no es criterio: es religión.
El criterio real es este: ¿este cambio reduce coste de cambio y riesgo futuro? Si no, cuidado.
Cuándo Clean Code ayuda de verdad
Clean Code se amortiza cuando el software vive en el mundo real: cambios frecuentes, equipo que rota, deuda que crece, auditorías, incidencias en producción, integraciones que cambian, y presión por entregar.
| Escenario | Clean Code aporta | Señal de que lo necesitas |
|---|---|---|
| Producto con vida larga | Coste de cambio controlado | Cada cambio “pequeño” se vuelve caro |
| Dominio con reglas | Claridad e invariantes | Reglas duplicadas y contradicciones |
| Integraciones externas | Límites y desacoplamiento | “Cambiar proveedor” es terror |
| Equipo creciendo/rotando | Onboarding y consistencia | Bus factor bajo, conocimiento tribal |
| Incidentes frecuentes | Diagnóstico y control de daño | MTTR alto, bugs “fantasma” |
Cuándo Clean Code es humo (y conviene decirlo)
Hay contextos donde perseguir “pureza” es mala inversión:
- Prototipo con fecha de caducidad: la prioridad es validar, no “arquitecturar”.
- CRUD simple y estable: meter capas y abstracciones suele empeorar.
- Equipo sin capacidad de mantenerlo: un estilo que nadie entiende se convierte en deuda.
Clean Code no es un objetivo moral: es una herramienta económica. Si no hay retorno, no se paga.
Ejemplos de buen y mal uso (sin lenguaje concreto)
1) Nombres: cuando el nombre dice la verdad (y cuando miente)
Un nombre bueno evita abrir la implementación. Un nombre malo obliga a leer “por dentro” y genera errores de uso.
Mal uso: nombres genéricos que ocultan intención y efectos: process, handle, calc, manager.
Buen uso: nombres que describen intención y, si aplica, efectos: calcularPrecioFinal, validarPedido, registrarPago, guardarPedido.
Mini guía
- Si una función tiene efectos (persistir, enviar, notificar), que el nombre lo sugiera.
- Si un concepto es de negocio, usa lenguaje del dominio, no términos técnicos.
- Evita “cajones de sastre” (Utils/Helper) salvo que sean realmente infraestructurales.
2) Separar “calcular” de “hacer” (control de daños)
El error más común en sistemas frágiles es mezclar reglas con IO: consultas, persistencia, red, colas, logs… Cuando mezclas, haces que testear y cambiar sea caro.
MAL: una operación hace de todo a la vez
- valida
- calcula
- persiste
- notifica
- cambia estado global
BIEN: separar decisiones de efectos
- regla pura: calcular_total(pedido)
- efecto explícito: guardar(pedido)
- efecto explícito: notificar(pedido)
Esto no es “estética”: es diseño para poder moverte sin romper el sistema.
3) Parámetros bandera (flag arguments): el “if” oculto
Cuando una función cambia comportamiento con banderas, la complejidad se dispara porque el contrato ya no es estable: es una función con múltiples personalidades.
Mal uso: procesar(pedido, modoRapido=true, enviarEmail=false, ...)
Buen uso: separar casos de uso o políticas explícitas: procesarPedidoNormal / procesarPedidoUrgente, o inyectar una estrategia clara.
4) Duplicación: el enemigo no son las líneas, son las decisiones repetidas
DRY mal entendido lleva a abstracciones genéricas que nadie entiende. DRY bien entendido elimina duplicación de comportamiento: reglas de negocio repetidas en sitios distintos.
Truco práctico
- Si dos fragmentos se parecen pero cambian por razones distintas: no los unifiques todavía.
- Si una regla de negocio se repite en 3 sitios: unifica o pagarás cada cambio tres veces.
5) Manejo de errores: el “Clean Code” que falla mal es mentira
Mucho código “parece limpio” hasta que falla. Y entonces descubres: errores tragados, reintentos infinitos, “null” silencioso, mensajes sin contexto.
Buen uso: errores como parte del contrato: qué puede fallar, cómo se reporta, y qué hace el sistema cuando falla.
- No ocultes errores; decide: reintento, fallback, propagación, o cortar.
- Log con contexto (correlation id, operación, usuario/tenant si aplica).
- Respuestas consistentes (en APIs: estructura de error coherente).
Clean Code y testing: el trípode real
Clean Code sin tests suele degenerar en refactor por deporte. Testing sin Clean Code suele degenerar en tests frágiles imposibles de mantener.
Lo que funciona de verdad en equipos:
- Tests para moverte sin miedo.
- Refactor incremental (pasos pequeños y comprobables).
- Automatización (formato, lint, análisis, gates en CI).
Cómo aplicar Clean Code en un equipo (sin guerras)
El fallo típico es convertirlo en “opiniones en PR”. Eso desgasta y no escala. Un equipo serio lo convierte en estándares automáticos y criterio compartido.
Mini guía: reglas de PR que suben calidad sin eternizar reviews
- PR pequeño (cambio acotado) > PR gigante “de limpieza”.
- El PR explica intención: qué cambia y por qué (2–5 líneas).
- Si hay riesgo: añade tests o evidencia (y si no se puede, documenta la excepción).
- Si hay refactor: que sea para habilitar cambio o reducir riesgo, no por estética.
Mini guía: “refactor con cabeza”
- Refactorizar = cambiar estructura sin cambiar comportamiento.
- Hazlo en pasos pequeños y verificables.
- Si no puedes verificar, lo primero es crear una red mínima (tests de caracterización o smoke).
Stack mínimo para sostener Clean Code (sin vendor-lock)
No se trata de herramientas “premium”. Se trata de instrumentar calidad para que no dependa de heroicidades.
| Capa | Qué implementar | Qué evita |
|---|---|---|
| Formato | Formatter + EditorConfig | Debates estéticos en PR |
| Lint / análisis | Linters + reglas de equipo | Smells repetidos |
| Calidad | Quality gate (deuda/duplicación/cobertura razonable) | Degradación silenciosa |
| Seguridad básica | Dependencias vulnerables + secrets scanning | Incidentes “por descuido” |
| CI | Pipeline que ejecute todo y bloquee degradaciones | “En mi máquina funciona” |
Dogmas que hacen daño (y cómo sustituirlos por criterio)
- “Funciones siempre minúsculas” → Sustituye por: cohesión y claridad al leer.
- “Cero comentarios” → Sustituye por: comenta el por qué, no el “qué” obvio.
- “Abstrae pronto” → Sustituye por: abstrae cuando el patrón sea real y estable.
- “Refactor continuo por estética” → Sustituye por: refactor para habilitar cambio o reducir riesgo.
Checklist final (para decidir si algo es “Clean” de verdad)
- ¿Un nuevo miembro del equipo lo entendería en 10 minutos?
- ¿El cambio de una regla toca 1–2 sitios o se dispersa?
- ¿Los efectos secundarios son explícitos?
- ¿Los errores se manejan de forma coherente?
- ¿Hay tests/evidencia suficiente para cambiar sin miedo?
- ¿La automatización evita debates repetidos?
Conclusión
Clean Code no es un estilo. Es una forma de reducir coste de cambio y riesgo futuro. Si se usa con criterio, se nota en estabilidad, velocidad y en la salud mental del equipo. Si se usa como dogma, se convierte en burocracia disfrazada de calidad.
En Gondor defendemos justo esto: menos religión, más ingeniería. Sistemas que se entienden, se testean y se pueden operar.