La PR que cambió mi forma de ver el código

El diff tenía 847 líneas. Verde por todas partes con adiciones, algunas líneas rojas de eliminación y, en apariencia, una reescritura completa de nuestro sistema de autenticación de usuarios. Había pasado tres semanas creando lo que creía una obra maestra de ingeniería de software moderna, con abstracciones elegantes, patrones de diseño aplicados con precisión quirúrgica y una arquitectura tan sofisticada que haría orgulloso a cualquier manual de ciencias de la computación.

Envié el pull request con la confianza de quien piensa que ha resuelto la autenticación para siempre.

La revisión de Daisy llegó dos horas después. No eran observaciones línea por línea, sino un único comentario que me heló el estómago: no podía entender qué intentaba hacer el código.

Daisy no era una desarrolladora junior. Llevaba ocho años construyendo sistemas en producción, había diseñado la mitad de nuestra infraestructura y podía depurar fallos en sistemas distribuidos con los ojos cerrados. Si ella no entendía mi código, el problema no era su comprensión.

El problema era mi comunicación.

Mirando atrás, veo con claridad dónde me equivoqué. Caí en la trampa que captura a muchos desarrolladores al inicio de su carrera: escribía para impresionar al compilador, no para comunicarme con personas.

Cada método era un escaparate de características del lenguaje que había aprendido recientemente. Usé genéricos avanzados donde habrían bastado tipos simples. Apliqué el patrón Strategy para un problema que tenía una única estrategia. Creé abstracciones supuestamente preparadas para futuros requisitos que solo existían en mi imaginación.

El flujo de autenticación, que debía leerse como una secuencia directa de validar credenciales, comprobar permisos y generar tokens, se convirtió en una excavación arqueológica entre capas de indirección. Cada abstracción era técnicamente correcta, pero en conjunto ocultaban la lógica de negocio bajo una montaña de ceremonia arquitectónica.

Había optimizado para el público equivocado. El código se escribe una vez y se lee cientos de veces. Yo optimicé para la única vez que lo escribí e ignoré las cientos de veces que alguien necesitaría entenderlo.

El comentario de Daisy no criticaba mis capacidades técnicas. Era retroalimentación sobre mis habilidades de comunicación. El software funcionaba perfectamente, pero fallaba en su trabajo principal: dejar claro el comportamiento del sistema a la siguiente persona que tuviera que trabajar con él.

La conversación que siguió cambió por completo mi forma de desarrollar. Daisy no reescribió mi código ni exigió cambios concretos. Hizo preguntas. Qué problema intentabas resolver. Por qué elegiste esta abstracción frente a un enfoque más simple. Si alguien se uniera al equipo mañana, cuánto tardaría en entender este flujo.

Me costó responder. No porque fueran preguntas difíciles, sino porque jamás me las había hecho. Estaba tan centrado en demostrar sofisticación técnica que olvidé el propósito real: crear sistemas que otras personas puedan entender, mantener y extender.

La reescritura me llevó cuatro días. Misma funcionalidad, un tercio de líneas, cero patrones de diseño. El flujo de autenticación se leía como una narración clara: recibir la solicitud, validar al usuario, comprobar permisos, generar la respuesta. Cada paso era explícito, cada decisión estaba documentada y cada caso límite se manejaba de forma obvia.

La nueva versión era aburrida. Y era brillante.

Cuando envié el pull request revisado, la aprobación de Daisy llegó en menos de una hora. Tres meses después, una nueva persona en el equipo entendió el sistema de autenticación en una sola tarde. Cuando una auditoría de seguridad exigió cambios en la generación de tokens, las modificaciones fueron directas. Seis meses después, cuando apareció un bug en producción, el diagnóstico tomó minutos en lugar de horas.

El código aburrido resultó ser la solución más sofisticada, sofisticada por su sencillez, no por su complejidad.

Aquel pull request me enseñó algo fundamental que nunca vi en la universidad: el código es un medio colaborativo. No solo instruyes a una máquina sobre qué hacer, también comunicas a otros desarrolladores por qué tomaste ciertas decisiones.

Desde entonces empecé a hacer preguntas distintas antes de escribir una sola línea. En lugar de cómo demuestro mis habilidades técnicas, me preguntaba cómo hago esto lo más claro posible para quien lo lee por primera vez. En lugar de cuál es la solución más elegante, pensaba cuál es la más obvia. En lugar de cómo lo hago flexible para cualquier requisito futuro, me centraba en qué debe hacer hoy y cómo dejarlo cristalino.

Pasé a escribir más comentarios, no para explicar lo que hace el código, que debería ser evidente, sino por qué se tomaron ciertas decisiones. Elegí nombres de variables que contaran su propósito, no que exhibieran vocabulario. Organicé funciones pensando en la comprensión humana antes que en la microeficiencia algorítmica.

Lo más importante, dejé de ver la revisión de código como un examen y empecé a verla como una herramienta de colaboración. Cada revisión es una oportunidad para validar que el código comunica su intención con claridad.

Las herramientas de IA modernas han potenciado este enfoque centrado en la claridad. El error común es usarlas para generar código más sofisticado, cuando su mayor valor es ayudarnos a pensar con mayor nitidez. Hoy, ante una lógica de negocio compleja, describo el problema en lenguaje llano y dejo que la IA me señale casos límite, simplificaciones posibles o puntos en los que mi explicación pierde claridad. Si no puedo explicar en términos simples qué hace mi código y por qué, es una señal de que lo he complicado innecesariamente.

Los hábitos que adquirí tras aquel tirón de orejas se han ido acumulando. Código claro significa menos errores y menos tiempo de depuración. Soluciones obvias se modifican con facilidad cuando cambian los requisitos, acelerando el desarrollo de nuevas funcionalidades. Decisiones bien documentadas evitan expediciones arqueológicas en el historial de git y suavizan el mantenimiento.

El impacto más grande está en la colaboración. Cuando tu código comunica con claridad, las revisiones se centran en la lógica de negocio, no en descifrar detalles de implementación. Cuando tus soluciones son obvias, más compañeros pueden contribuir. Cuando tus decisiones se entienden, la transferencia de conocimiento fluye de forma natural.

Las personas que avanzan más rápido en su carrera no son las que implementan algoritmos más complejos o dominan las características más esotéricas del lenguaje. Son quienes escriben el código más fácil de leer, modificar, extender y depurar.

La sofisticación técnica sin claridad de comunicación es complejidad costosa.

La próxima vez que vayas a enviar un pull request, lee tu código como si acabaras de unirte al equipo. Qué preguntas surgirían. Qué contexto estás asumiendo. Qué decisiones te parecen obvias a ti pero podrían confundir a otra persona.

En Q2BSTUDIO vivimos esta filosofía cada día. Somos una empresa de desarrollo de software que construye aplicaciones a medida y software a medida con foco en claridad, mantenibilidad y valor de negocio. Combinamos arquitectura pragmática con especialistas en inteligencia artificial, ciberseguridad, automatización de procesos, servicios cloud aws y azure, servicios inteligencia de negocio y power bi para que tus sistemas crezcan de forma segura y sostenible.

Usamos IA para empresas de manera responsable, desde agentes IA que ayudan a razonar sobre reglas de negocio hasta asistentes que validan supuestos y descubren casos límite. Si quieres llevar esa ventaja a tu organización, descubre cómo aplicamos inteligencia artificial con resultados medibles, sin añadir complejidad innecesaria.

Si te preocupa la resiliencia y la seguridad, contamos con equipos de ciberseguridad y pentesting que trabajan codo a codo con ingeniería para anticipar riesgos. Si tu reto pasa por el dato, impulsamos inteligencia de negocio y analítica avanzada con power bi para traducir métricas en decisiones. Y si estás migrando o escalando, nuestros expertos en servicios cloud aws y azure priorizan el diseño claro, automatizable y trazable.

Cada línea de código es una línea de comunicación. La maestría no está en lo rebuscado, sino en resolver problemas de forma tan clara que la complejidad deje de ser necesaria. El código que transforma el mundo es el que otros pueden entender lo bastante bien como para mejorarlo.

En Q2BSTUDIO estamos listos para acompañarte desde la estrategia hasta la implementación, con un enfoque que pone la comprensión primero y el ego después. Escríbenos y construyamos juntos soluciones nítidas, seguras y escalables con aplicaciones a medida, ia para empresas y decisiones impulsadas por datos.

Leena