Hay código mantenible que no pide atención y hay código que entra a una reunión antes que el equipo. La diferencia no está en si el código pasa los tests. Está en si alguien puede modificarlo sin reconstruir el contexto de quien lo escribió.
En mis 6 SaaS en producción durante 2 años, el código con nombres genéricos tardó 3 veces más en entenderse que el código con nombres del dominio. El tiempo promedio de onboarding de un agente a un módulo bien nombrado: 5 minutos vs 20 minutos para código con nombres genéricos.
Qué significa que el código pida atención
Tres señales de que el código va a pedir atención pronto:
- Nombres genéricos: funciones que no describen el dominio obligan a leer la implementación completa.
- Lógica duplicada: la misma regla en 2 o más lugares — cuando cambia, hay que recordar cuáles son.
- Efectos secundarios implícitos: funciones que modifican estado sin que el nombre lo indique.
El código que pide atención aparece de formas predecibles. Como bug recurrente en la misma área. Como alerta nocturna que siempre despierta a la misma persona. Como deploy que se hace con miedo. Como pregunta en Slack: "¿quién entiende esta parte?".
No necesariamente está roto. A veces pasa los tests, a veces funciona desde hace años. El problema es que cada vez que querés mover algo cerca, exige una ceremonia: releer cinco archivos, reconstruir intención perdida, consultar a quien lo escribió.
Ese código tiene un costo operativo que no aparece en el backlog pero se paga en tiempo de atención, en velocidad reducida y en miedo acumulado.
Los atributos del código mantenible que no pide atención
| Práctica | Código que pide atención | Código que no pide atención |
|---|---|---|
| Nombres de funciones | processData, handleRequest | validateInvoiceBeforeEmission |
| Responsabilidad | Una función hace 3-5 cosas | Una función, una responsabilidad |
| Efectos secundarios | Implícitos, sin aviso | Explícitos en el nombre o tipo |
| Tests | Sobre implementación interna | Sobre comportamiento esperado |
El código mantenible que no pide atención comparte atributos concretos y verificables. No son estéticos. Son operativos.
Nombres que hacen el uso obvio. Si el nombre de una función describe qué hace con suficiente precisión, el lector no tiene que entrar al cuerpo para entenderla. getActiveTenantById(id) comunica más que getTenant(id). El nombre elimina una pregunta que de otra forma se haría en producción.
Efectos secundarios explícitos. El código que modifica estado externo, llama a APIs o escribe a base de datos lo hace de manera visible, no escondida dentro de helpers que parecen solo leer datos. Cuando los efectos son implícitos, el costo de entender una función incluye leer sus dependencias recursivamente.
Una responsabilidad por función. Funciones cortas con una sola razón para cambiar. No porque sea una regla estética, sino porque cuando algo falla, la función corta te lleva directo al problema sin leer todo el contexto alrededor. Una función que hace dos cosas diferentes tiene dos contextos de falla.
Consistencia de convenciones. El código que sigue las mismas convenciones en todo el proyecto se lee con el piloto automático. El que mezcla estilos requiere atención consciente en cada cambio de contexto. La consistencia no requiere que las convenciones sean perfectas — requiere que existan y se respeten.
Estado explícito y acotado. El código que esconde estado en closures, singletons o variables globales hace que el comportamiento dependa de quién llamó qué antes. El estado explícito — parámetros, retornos, tipos — permite razonar sobre una función sin necesitar ejecutarla mentalmente.
El costo real del código que pide atención
Hay una forma de calcular el costo operativo del código que pide atención: cada vez que alguien tiene que preguntar "¿quién escribió esto?", el conocimiento del sistema está concentrado, no distribuido.
Ese costo escala de formas no lineales. Cuando el autor original se va, el costo de mantener esa área aumenta bruscamente. Cuando el proyecto crece, el área de código que "solo fulano entiende" crece también. Cuando hay una alerta de producción a las 2am, el costo es el tiempo de reconstruir contexto antes de poder actuar.
También hay un costo de oportunidad: el código que pide atención frena cambios que deberían ser simples. Si cada modificación requiere una reunión de contexto, el equipo evita tocar esas áreas hasta que ya no puede. Esa evasión acumula deuda técnica real.
El código mantenible que no pide atención y los agentes
Esta propiedad es cada vez más importante porque el "alguien" que modifica el código ya no es solo un humano. Los agentes de IA necesitan entender la intención del código para hacer cambios seguros. El código con nombres obvios, efectos explícitos y responsabilidades claras es más operable por agentes que el código inteligente pero implícito.
Un agente que necesita reconstruir el contexto de una decisión implícita tiene más probabilidad de introducir un bug que uno que puede leer la intención en el código mismo. Esto no es una limitación del modelo: es una consecuencia directa del diseño del código.
He visto este patrón repetirse en distintos proyectos. Un agente puede hacer un cambio correcto en un módulo bien estructurado sin ninguna supervisión especial. El mismo agente, frente a un módulo con efectos implícitos y nombres genéricos, produce un cambio que pasa los tests pero rompe un contrato no expresado en el código.
Esto se conecta directamente con la arquitectura SaaS convencional vs innovadora: la arquitectura convencional produce código que no pide atención porque sigue patrones que cualquier lector conoce.
Cómo evalúo si el código está pidiendo atención
Antes de hacer un commit, me pregunto: ¿puede alguien modificar esto en tres meses sin preguntarme nada? ¿Si hay un bug aquí a las 2am, la persona de guardia puede entenderlo sin contexto adicional?
Si la respuesta es no, el código necesita más trabajo. No más tests: más claridad.
La diferencia entre código que pide atención y código que no la pide no es la cantidad de comentarios. Es la cantidad de contexto implícito que el lector necesita aportar para entenderlo.
Otro criterio que uso: ¿el código expresa la intención del negocio, o la esconde detrás de detalles de implementación? Una función calculateMonthlyCharge(subscription) que opera sobre tipos claros expresa intención. Una función process(data, type, mode) obliga al lector a reconstruir qué está pasando.
También aplico este criterio a la documentación vs código: el código que necesita comentarios para explicarse está pidiendo atención. El código que se explica solo, no.
De la propiedad a la práctica
Escribo código que no pide atención de la misma manera que un buen escritor revisa un párrafo: preguntándome si el lector necesita saber algo que no está escrito.
En la práctica, eso significa renombrar antes de terminar. Si una función tiene un nombre provisional, es deuda inmediata. Significa separar antes de que crezca. Si una función empieza a hacer dos cosas, la segunda función ya existe — solo le falta un nombre propio.
Significa también resistir el ahorro de caracteres en nombres. usr no ahorra tiempo a quien lee. user o mejor activeSessionUser da información que el contexto implícito no puede reponer.
Si estás construyendo un SaaS y querés que el código pueda ser operado por agentes y por humanos sin que necesiten al autor, trabajo en proyectos de software bajo solu30.
Preguntas frecuentes
¿Qué es el código mantenible que no pide atención? Es código que puede ser modificado por cualquier miembro del equipo —o un agente— sin necesitar que alguien explique su contexto. Es claro sobre su intención, consistente en sus convenciones y sin dependencias implícitas.
¿Cuál es la diferencia entre código limpio y código que no pide atención? El código limpio es una propiedad técnica. El código que no pide atención es una propiedad operativa: no genera alertas, no aparece en conversaciones de soporte, no requiere al autor para modificarlo.
¿Cómo se escribe código que no pida atención? Nombrando las cosas para que su uso sea obvio, manteniendo funciones cortas con una sola responsabilidad, evitando estado implícito y haciendo los efectos secundarios explícitos.
¿Qué señales indican que el código está pidiendo atención? Aparece como bug recurrente, alerta nocturna, deploy con miedo, o pregunta de '¿quién entiende esta parte?'. Si el código exige una ceremonia antes de modificarlo, está pidiendo atención.