Código que humanos sí puedan mantener

Tu equipo puede entregar rápido y aun así dejar una base de código que nadie quiere tocar. Ese es el problema real: no basta con que una funcionalidad salga hoy si mañana cuesta el doble entenderla, probarla o cambiarla. Cuando el código está escrito solo para pasar el siguiente sprint, la factura llega después, casi siempre en forma de bugs, retrabajo y reuniones para descifrar qué quiso hacer alguien hace tres meses.

La frase “write code like a human will maintain it” no va de escribir bonito por estética. Va de asumir una verdad simple: el software vive más tiempo que la emoción del release. Si tú no puedes explicar una pieza de código en dos minutos, si no puedes cubrirla con pruebas sin pelearte con dependencias ocultas, o si cada cambio rompe tres cosas, entonces no estás construyendo velocidad. Estás acumulando deuda técnica.

Por qué la velocidad sola engaña

La velocidad de entrega se ve bien en un tablero. Un equipo cierra historias, sube PRs y despliega más seguido. Pero si cada entrega agrega complejidad innecesaria, la velocidad aparente baja en los siguientes ciclos. Es como apretar el acelerador con el freno de mano puesto: el indicador sube, pero el sistema se desgasta.

Esto pasa mucho cuando el equipo premia solo el output. Se mide cuántas historias entraron a producción, pero no cuánto costó mantenerlas. En la práctica, eso produce código con nombres ambiguos, funciones gigantes, lógica duplicada y pruebas frágiles. Todo parece avanzar hasta que llega el primer cambio de alcance mediano y nadie sabe por dónde empezar.

La deuda técnica no es un concepto abstracto

La deuda técnica tiene síntomas muy concretos. Un ejemplo típico: una pantalla de checkout que funciona, pero depende de 4 servicios, 2 funciones utilitarias con nombres genéricos y una validación copiada en tres lugares. Si cambia la regla de impuestos, el equipo toca algo pequeño y rompe el flujo de cupones. El bug no nació por mala suerte; nació porque el código era difícil de leer y difícil de aislar.

Otro caso común en equipos de LatAm es el de integraciones con pasarelas de pago, facturación electrónica o mensajes por WhatsApp. Como hay presión por salir, se mete la lógica en el componente o en el controlador. Funciona. Luego llega una segunda integración para otro país o una nueva versión del proveedor, y el cambio se vuelve una cirugía.

El costo real aparece en el día a día

No hace falta esperar un incidente grave para ver el costo. Se nota en cosas pequeñas: PRs que tardan días porque nadie entiende el contexto, bugs repetidos porque no hay pruebas alrededor de la lógica crítica, y onboarding lento porque los nuevos integrantes dependen de explicaciones orales para entender el sistema.

Un equipo sano no se pregunta solo “¿lo terminamos?”. También pregunta “¿lo vamos a poder mantener en 6 meses?”. Esa pregunta cambia la forma de escribir código desde el primer commit.

Escribir para humanos empieza por el nombre

Los nombres son la primera capa de mantenimiento. Si una variable se llama data, info, temp o result2, estás obligando a quien lee a adivinar. Y adivinar en software sale caro. Un nombre bueno reduce la necesidad de comentarios, porque explica la intención sin rodeos.

No se trata de inventar nombres largos por deporte. Se trata de ser preciso. invoiceTotalWithTax dice más que amount. retryPaymentRequest dice más que handlePayment. activeSubscriptionCount es más útil que count. El nombre correcto ahorra tiempo cada vez que alguien vuelve al archivo.

Nombres que ayudan a entender intención

Piensa en esta diferencia:

// Difícil de leer
const x = orders.filter((o) => o.s === "paid");

// Más claro
const paidOrders = orders.filter((order) => order.status === "paid");

El segundo ejemplo no solo se lee mejor. También es más fácil de buscar, de probar y de refactorizar. Cuando el nombre expresa el dominio, el código se vuelve más cercano al negocio y menos a un acertijo técnico.

Comentarios: pocos, útiles y vivos

Los comentarios no reemplazan un mal diseño. Si necesitas explicar cada línea, el problema no es la falta de comentarios, sino la falta de claridad en el código. Un buen comentario explica por qué existe una decisión rara, no qué hace una línea obvia.

Por ejemplo, sí vale la pena comentar una regla fiscal específica, una limitación de un proveedor externo o una decisión temporal mientras migras un sistema. Lo que no ayuda es escribir “incrementa i en 1” al lado de i++. Eso envejece mal y llena el archivo de ruido.

Estructura pequeña, cambios pequeños

Si una función hace demasiadas cosas, la lectura se vuelve costosa y el riesgo de romper algo sube. Una buena regla práctica es que cada unidad de código tenga una sola responsabilidad visible. No porque exista una ley mágica, sino porque eso hace más fácil probarla, reemplazarla y entenderla.

En equipos que entregan rápido, la tentación es juntar validación, transformación, acceso a datos y side effects en el mismo bloque. Eso acelera el primer cierre, pero complica los siguientes. Separar responsabilidades no es burocracia; es una inversión en cambios futuros.

Señales de que una función ya creció demasiado

Si te pasa una o más de estas cosas, probablemente ya conviene dividirla:

1. Tiene más de 50 a 80 líneas y ya no cabe en una sola pantalla sin perder contexto.
2. Usa más de 3 niveles de anidación.
3. Mezcla lógica de negocio con llamadas HTTP, acceso a base de datos y formateo de respuesta.
4. No puedes escribir una prueba sin montar medio sistema alrededor.
5. El nombre de la función suena genérico, como process, handle o manage.

No necesitas convertir todo en microfunciones. Solo necesitas que cada parte tenga un propósito claro. Si una función valida, otra calcula y otra persiste, cada una se vuelve más fácil de testear y de cambiar.

Un ejemplo simple de separación

function calculateDiscount(total: number, couponPercent: number) {
  return total * (couponPercent / 100);
}

function applyDiscount(total: number, couponPercent: number) {
  const discount = calculateDiscount(total, couponPercent);
  return total - discount;
}

Aquí la lógica se puede probar por separado. Si mañana cambia la forma de calcular el descuento, no tienes que tocar el flujo completo del checkout. Y si aparece una regla nueva, como un tope máximo por campaña, puedes añadirla sin reescribir todo.

Pruebas que protegen cambios, no solo cobertura

Tener pruebas no significa tener seguridad. Puedes tener 90% de coverage y aun así romper producción si las pruebas solo verifican detalles internos o caminos triviales. Lo que importa es que las pruebas protejan el comportamiento que de verdad le importa al negocio.

Una buena prueba le responde a esta pregunta: si cambio algo importante, ¿me entero rápido? Si la respuesta es sí, el código tiene una red de seguridad útil. Si la respuesta es no, las pruebas son decoración.

Qué sí conviene probar

En general, conviene poner foco en:

• Reglas de negocio con impacto económico o legal.
• Validaciones de entrada que evitan estados inválidos.
• Integraciones con APIs externas, usando mocks o contratos claros.
• Casos borde que ya causaron bugs antes.
• Funciones puras con cálculos importantes.

No hace falta testear cada getter o cada render sin lógica. Eso suele agregar ruido y mantenimiento extra. En cambio, una prueba sobre la lógica de impuestos, el cálculo de envío o el estado de una suscripción sí puede ahorrarte horas de soporte.

Tabla práctica de decisiones de prueba

Si trabajas con equipos distribuidos o con rotación alta, las pruebas también funcionan como documentación ejecutable. Un nuevo dev puede leer un test y entender qué espera el sistema sin perseguir a nadie por Slack.

Refactorizar sin parar el delivery

Refactorizar no significa detener el producto por semanas. Significa mejorar la estructura en pasos pequeños, mientras sigues entregando valor. El truco está en no intentar arreglar todo de una vez. Si esperas el momento perfecto, nunca refactorizas.

La mejor estrategia suele ser incremental: tocar un área, cubrirla con pruebas, simplificarla y seguir. Así reduces riesgo y mantienes el flujo de entregas. No necesitas una gran migración para empezar a escribir mejor código; necesitas disciplina en cada PR.

Un flujo práctico para tu próximo cambio

1. Lee el código existente antes de editarlo.
2. Escribe o ajusta una prueba que capture el comportamiento actual.
3. Haz el cambio más pequeño posible para resolver el problema.
4. Renombra variables o extrae funciones si eso mejora la lectura.
5. Revisa si el cambio dejó una dependencia innecesaria.
6. Pide revisión enfocada en claridad, no solo en que “funcione”.

Ese orden importa. Si primero cambias y luego intentas entender, te expones a tocar más de lo necesario. Si primero estabilizas con pruebas, puedes refactorizar con menos miedo.

Cómo evitar el refactor eterno

Hay equipos que convierten el refactor en una excusa para no entregar. También hay equipos que nunca refactorizan y terminan atrapados. El punto medio es claro: cada cambio funcional debería dejar el código un poco mejor que como estaba, al menos en la zona tocada.

No hace falta reescribir módulos enteros para mejorar la mantenibilidad. A veces basta con extraer una función, renombrar una variable o separar una condición compleja en pasos legibles. Eso reduce la fricción acumulada sin frenar el roadmap.

Cómo se ve esto en un equipo real

Imagina un equipo que mantiene una plataforma de e-commerce en Ecuador y Colombia. Un día necesitan cambiar la lógica de promociones para que una campaña aplique solo en ciertos métodos de pago. Si el código está mezclado, el cambio toca frontend, backend y una capa de integración con el proveedor de pagos. El PR se vuelve difícil de revisar y el riesgo de romper algo sube.

Ahora imagina el mismo caso con código mantenible. La regla de promociones vive en una función aislada, las pruebas cubren escenarios clave y los servicios externos están encapsulados. El cambio sigue siendo trabajo, pero no es una excavación. Puedes mover una pieza sin desarmar todo el sistema.

Qué gana el equipo cuando el código es legible

• Menos tiempo en code review porque el propósito está claro.
• Menos bugs por cambios colaterales.
• Onboarding más rápido para personas nuevas.
• Mayor confianza al hacer releases frecuentes.
• Menos dependencia de una sola persona que “sí entiende esa parte”.

Eso también impacta la cultura. Cuando el código es entendible, el equipo conversa sobre decisiones reales. Cuando no lo es, la conversación se va en adivinar intenciones y reconstruir contexto.

La regla que más ayuda en PRs

Antes de aprobar un PR, pregúntate: ¿esto lo entendería alguien nuevo en el equipo dentro de 3 meses? Si la respuesta es no, entonces todavía falta trabajo. No necesitas perfección, pero sí un estándar mínimo de claridad.

Si quieres una referencia sólida sobre buenas prácticas de mantenibilidad y diseño, la documentación de TypeScript sobre narrowing y tipos puede ayudarte a reducir ambigüedad en código real: https://www.typescriptlang.org/docs/handbook/2/narrowing.html. Para pruebas, la guía oficial de Testing Library explica cómo enfocarte en comportamiento y no en implementación: https://testing-library.com/docs/.

Tabla resumen

Es fácil confundirse y pensar que mantener código es solo una tarea de orden. En realidad, es una decisión de negocio. Cada vez que eliges claridad sobre atajos innecesarios, estás bajando el costo de los siguientes cambios. Y en software, ese costo acumulado define si tu equipo entrega con confianza o con miedo.

El objetivo no es escribir código perfecto. El objetivo es escribir código que otro humano pueda entender, probar y evolucionar sin tener que reconstruir la historia completa del proyecto. Si logras eso, la velocidad deja de ser una ilusión y se vuelve sostenible.