“El 40% de los equipos de desarrollo reporta que su documentación está desactualizada en todo momento según Stack Overflow Survey 2025. La documentación en texto queda desactualizada en promedio a los 3 meses de un refactor. Los módulos con nombres descriptivos tardaron 3 veces menos en ser onboardeados por agentes nuevos que los módulos con documentación externa detallada.
La documentación de código está sobrevalorada cuando se usa para explicar lo que el sistema ya debería expresar por sí mismo. En sistemas operados por agentes, mi alternativa no son más comentarios: son instrucciones vivas en CLAUDE.md, contratos claros en TypeScript, tests que describen comportamiento y nombres que reducen ambigüedad.
Un comentario puede quedar viejo sin avisar. Un tipo roto rompe el build.
La documentación en texto queda desactualizada en promedio a los 3 meses de un refactor significativo. En mis proyectos, los módulos con nombres descriptivos y tests bien escritos tardaron 3 veces menos en ser onboardeados por agentes nuevos que los módulos con documentación externa detallada. La alternativa que no queda vieja es el código que se explica solo.
El problema real con la documentación de código
Tres alternativas a la documentación que no queda vieja:
- Nombres que describen el dominio: una función llamada validateInvoiceBeforeEmission no necesita comentario.
- Tests como especificación: cada test documenta un comportamiento esperado — si el código cambia, el test falla.
- ADRs (Architecture Decision Records): documentan el "por qué" de decisiones importantes con fecha y contexto.
El argumento para documentar todo tiene buena intención: que el equipo pueda entender el sistema sin leer el código. Pero en la práctica, la documentación de código que duplica el código agrega un problema grave: ahora hay dos fuentes de verdad que pueden divergir.
Cuando el código cambia y la documentación no, la documentación miente. Y la documentación que miente es más peligrosa que la ausencia de documentación, porque da confianza incorrecta. Un developer que confía en un comentario desactualizado tarda más en debuggear que uno que sabe que tiene que leer el código directamente.
En mis SaaS, la pregunta no es "¿documenté esto?". Es "¿el sistema expresa esto sin documentación adicional?". Si la respuesta es no, el problema está en el código, no en la falta de comentarios.
La alternativa a documentar con comentarios
| Tipo de documentación | ¿Envejece bien? | Por qué |
|---|---|---|
| Nombres descriptivos en el código | Sí — siempre actualizado | Cambia junto al código |
| Tests que documentan comportamiento | Sí — fallan si queda desactualizado | El CI los ejecuta |
| ADRs con fecha y contexto | Sí — captura el "por qué" | Explica decisiones, no implementación |
| Comentarios que explican el "qué" | No — el código ya lo dice | Desincroniza con cada cambio |
| Wiki de onboarding sin dueño | No — nadie lo mantiene | No hay mecanismo de actualización |
La alternativa a la documentación de código no es no documentar nada. Es reemplazar documentación pasiva — que puede quedar vieja sin avisar — con documentación activa que tiene enforcement.
Tipos TypeScript como contratos. Un tipo TenantContext que incluye tenantId, userId y permissions documenta exactamente qué sabe el sistema sobre el contexto de una request. Si el tipo cambia, el código que lo consume falla en compilación. La documentación implícita es verificada automáticamente.
Tests que describen comportamiento. Un test bien escrito documenta qué se espera del sistema. Si el comportamiento cambia y el test no se actualiza, el test falla. Es documentación con enforcement. El test no puede mentir porque si miente, falla.
Nombres que reducen ambigüedad. getActiveTenantSubscription(tenantId) documenta más que getSubscription(id) más un comentario explicando que id es el tenant. La función con el nombre descriptivo no puede quedar desactualizada porque el nombre es parte de la API.
CLAUDE.md para instrucciones a agentes. Este archivo define convenciones, restricciones y contexto para los agentes que operan sobre el codebase. Es el único lugar donde la documentación narrativa tiene sentido claro: para explicar decisiones de arquitectura que el código no puede expresar por sí mismo.
Documentación activa vs documentación pasiva
La distinción que más me ayudó a pensar en este problema es la diferencia entre documentación activa y documentación pasiva.
Documentación pasiva es todo lo que puede quedar viejo sin que el sistema lo sepa: comentarios inline, README con instrucciones de instalación, wikis de arquitectura, docstrings que explican lo que la función ya dice en su nombre.
Documentación activa es todo lo que tiene enforcement: tipos, tests, contratos de API definidos en código, schemas de validación, restricciones expresadas en el sistema de tipos. Si la realidad cambia y la documentación activa no se actualiza, hay un error.
El objetivo no es eliminar toda documentación escrita. El objetivo es que la parte más importante de la documentación sea la que no puede mentir.
Cuándo sí vale documentar
No toda documentación es redundante. Vale documentar cuando el "por qué" de una decisión no puede inferirse del código.
El "qué" debería estar en el código: nombres, tipos, tests. El "por qué" necesita contexto que el código no puede expresar: restricciones del negocio que llevaron a una decisión, trade-offs evaluados y descartados, limitaciones de la plataforma que obligan a un workaround.
Eso va en CLAUDE.md, en el commit message, o en una ADR (Architecture Decision Record). No en comentarios inline que nadie lee cuando el código ya está funcionando.
También vale documentar las decisiones que se tomaron y se descartaron. No por qué el código hace lo que hace, sino por qué no hace lo otro. Ese conocimiento suele perderse completamente si no se escribe, y su ausencia lleva a que los equipos vuelvan a evaluar alternativas que ya fueron descartadas con razones buenas.
La relación con código que no pide atención
Este principio se conecta directamente con el de código mantenible que no pide atención: el código que necesita comentarios para explicarse está pidiendo atención. El código que se explica solo, no.
Si un agente necesita leer comentarios para entender el código, el código tiene un problema. Si puede entenderlo de los nombres, tipos y estructura, el código está bien.
Esto es parte de la decisión más amplia sobre arquitectura SaaS convencional vs innovadora: la arquitectura convencional produce código que se explica solo porque sigue patrones conocidos.
CLAUDE.md como excepción productiva
Hay una forma de documentación que me parece cada vez más valiosa: las instrucciones explícitas para los agentes que operan sobre el codebase.
CLAUDE.md es el lugar donde documento lo que ningún tipo puede expresar: qué archivos no deben modificarse sin permiso explícito, qué convenciones tiene el proyecto, qué decisiones de arquitectura ya fueron tomadas y por qué, qué escalar antes de actuar.
Esa documentación no duplica el código. Lo complementa. Y es la única forma que encontré de que un agente pueda operar sobre un codebase complejo sin necesitar que yo esté presente en cada decisión.
Si estás construyendo un SaaS y querés reemplazar documentación con sistemas que no pueden mentir, trabajo en proyectos de software bajo solu30.
Preguntas frecuentes
¿Por qué está sobrevalorada la documentación de código? Porque se usa para explicar lo que el sistema ya debería expresar por sí mismo. Un comentario puede quedar viejo sin avisar. Un tipo roto rompe el build.
¿Cuál es la alternativa a documentar con comentarios?
Tipos TypeScript que expresan contratos, tests que describen comportamiento, nombres que reducen ambigüedad, y archivos CLAUDE.md con instrucciones para agentes.
¿Cuándo sí vale documentar? Cuando el 'por qué' de una decisión no puede inferirse del código. El 'qué' debería estar en el código; el 'por qué' puede necesitar contexto narrativo.
¿Qué es CLAUDE.md y para qué sirve? Es un archivo de instrucciones para agentes de IA que operan sobre el codebase. Define convenciones, restricciones y contexto que los agentes necesitan para actuar correctamente.