Existe una creencia ampliamente extendida en el mundo del desarrollo de software: que un sistema complejo necesita documentación extensa para ser mantenible. Esta creencia nace de una confusión fundamental entre complejidad accidental y complejidad esencial.
La complejidad esencial es inherente al problema que resuelves —no puedes eliminarla sin cambiar los requerimientos. La complejidad accidental es aquella que tú introduces con tus decisiones de diseño, y esta sí puede y debe eliminarse.
“El código que necesita ser explicado generalmente necesita ser reescrito, no documentado.”
El código que se explica a sí mismo #
Cuando un desarrollador escribe calcularImpuesto(precio, region) en lugar de calc(p, r), no está siendo pedante —está documentando la intención en el único lugar donde la documentación no puede desincronizarse: el código mismo.
Los nombres de variables, funciones y clases son la primera capa de documentación. Una función llamada procesarOrden que en realidad también envía emails, actualiza inventario y genera facturas no tiene un problema de documentación —tiene un problema de responsabilidad única.
Arquitectura como comunicación #
La estructura de carpetas de un proyecto, la separación de capas, los patrones aplicados consistentemente —todo esto comunica decisiones de diseño a cualquier desarrollador que llegue después.
Un proyecto con una arquitectura hexagonal bien implementada no necesita un documento explicando por qué las dependencias apuntan hacia el dominio. La estructura lo dice sola.
# Esto no necesita comentario
def calcular_total_con_descuento(precio: float, porcentaje_descuento: float) -> float:
descuento = precio * (porcentaje_descuento / 100)
return precio - descuento
# Esto sí necesita refactoring, no comentarios
def calc(p, d):
return p - (p * (d / 100))¿Qué documentación sí tiene valor? #
Esto no significa que la documentación no tenga valor. Los ADRs (Architecture Decision Records) que explican el por qué de decisiones no obvias, los diagramas de flujo para procesos de negocio complejos, el README que explica cómo ejecutar el proyecto localmente —todo esto tiene su lugar.
La diferencia está en documentar el razonamiento, no la mecánica. Si necesitas explicar cómo funciona tu código, ese es el síntoma. La causa es código que no comunica su intención por sí mismo.
La deuda técnica como deuda de legibilidad #
Gran parte de lo que llamamos deuda técnica es en realidad deuda de legibilidad acumulada. Código que alguna vez tuvo sentido en su contexto original pero que hoy nadie entiende sin estudiarlo extensivamente.
En The Silent Algorithm, cuando medimos la calidad de nuestro código, una de las métricas más importantes es cuánto tiempo tarda un desarrollador nuevo en entender un módulo y hacer su primer cambio con confianza. Si ese tiempo supera los 30 minutos para un módulo de tamaño mediano, tenemos trabajo que hacer —no documentación que escribir.
El código bien escrito no es un ideal inalcanzable. Es una disciplina. Y como toda disciplina, requiere práctica deliberada, revisión de pares y el coraje de refactorizar cuando algo duele.