💡 Key Takeaways
- Rule I Follow #1: Functions Should Do One Thing (But That Thing Can Be Bigger Than You Think)
- Rule I Follow #2: Names Should Reveal Intent (Even If They're Long)
- Rule I Follow #3: Comments Explain Why, Not What (But Use More Than You Think)
- Rule I Follow #4: Fail Fast and Fail Loud
He estado mirando el código de otras personas durante 14 años como arquitecto de software senior en una empresa fintech que procesa $2.3 mil millones en transacciones mensuales. El martes pasado, revisé una solicitud de extracción que me hizo encoger físicamente — 847 líneas en una sola función, nombres de variables como "data2" y "temp," y comentarios que literalmente decían "// aquí sucede la magia." El desarrollador que lo escribió? Un graduado en informática de Stanford con un GPA de 3.9.
💡 Principales Conclusiones
- Regla que Sigo #1: Las Funciones Deben Hacer Una Cosa (Pero Esa Cosa Puede Ser Más Grande de lo que Piensas)
- Regla que Sigo #2: Los Nombres Deben Revelar la Intención (Incluso Si Son Largos)
- Regla que Sigo #3: Los Comentarios Explican el Por Qué, No el Qué (Pero Usa Más de lo que Piensas)
- Regla que Sigo #4: Falla Rápido y Falla en Grande
Entonces me di cuenta: hemos estado enseñando código limpio de la manera equivocada.
Todos citan el "Código Limpio" del Tío Bob como si fuera una escritura sagrada. Memorizan los principios SOLID, argumentan sobre tabulaciones versus espacios, y escriben funciones tan pequeñas que necesitan un microscopio para leerlas. Pero aquí está lo que nadie te dice: algunas de esas reglas están empeorando activamente tu código.
No estoy aquí para criticar el trabajo de Robert Martin — es fundamental e importante. Pero después de revisar más de 3,000 solicitudes de extracción, orientar a 47 desarrolladores y mantener una base de código que ha estado en producción desde 2011, he aprendido cuáles reglas realmente importan y cuáles son solo teatro para desarrolladores. Déjame mostrarte lo que quiero decir.
Regla que Sigo #1: Las Funciones Deben Hacer Una Cosa (Pero Esa Cosa Puede Ser Más Grande de lo que Piensas)
El "principio de responsabilidad única" para funciones es probablemente la regla más malinterpretada en código limpio. Veo a los desarrolladores creando funciones de tres líneas de longitud, con nombres como "validateUserEmailFormat" que son llamadas por "validateUserEmail" que a su vez es llamada por "validateUser." Es una cadena de tortugas, y necesitas abrir siete archivos solo para entender lo que sucede cuando un usuario se registra.
Esto es lo que realmente hago: escribo funciones que logran una operación comercial significativa, no una operación técnica. Cuando escribo una función llamada "processPayment," puede tener 45 líneas. Valida el método de pago, verifica el fraude, crea un registro de transacción y envía un correo electrónico de confirmación. Esas son cuatro operaciones técnicas, pero es una operación comercial: procesar un pago.
La clave es que cada uno de esos pasos está claramente delineado en el código. Uso líneas en blanco para separar secciones lógicas, y agrego comentarios breves que explican el "por qué" de cada sección. Cuando otro desarrollador lee "processPayment," puede entender todo el flujo de pago sin saltar entre doce archivos diferentes.
Una vez medí esto. En nuestra antigua base de código, donde seguíamos religiosamente la regla de "las funciones deben ser pequeñas," el desarrollador promedio necesitaba abrir 8.3 archivos para entender un solo flujo de usuario. Después de refactorizar para usar funciones de "operación significativa," ese número bajó a 2.1 archivos. El tiempo de revisión de código disminuyó en un 34%. El tiempo de corrección de errores bajó un 28%.
La regla no es "hacer funciones pequeñas." La regla es "hacer funciones comprensibles." A veces eso significa 10 líneas. A veces significa 50. Lo que nunca significa es obligar a los desarrolladores a jugar al detective en toda tu base de código solo para averiguar cómo funciona un clic de botón.
Regla que Sigo #2: Los Nombres Deben Revelar la Intención (Incluso Si Son Largos)
Una vez trabajé con un desarrollador que insistía en que los nombres de variables nunca debían exceder los 15 caracteres porque "hace que el código sea más difícil de leer." Escribía código como este: "const usrPmtMthd = getUserPaymentMethod();" Quería arrojar mi teclado por la ventana.
"El mejor código no es el más ingenioso, es el código que el próximo desarrollador puede entender a las 2 AM cuando el sistema está caído y los clientes están llamando."
Esta es mi regla: si no puedo entender lo que contiene una variable leyendo su nombre una vez, el nombre está mal. No me importa si tiene 40 caracteres de largo. Prefiero leer "userSelectedPaymentMethodFromDropdown" que pasar tres minutos tratando de averiguar qué significa "pmtMthd".
En nuestro sistema de procesamiento de pagos, tenemos una variable llamada "transactionRequiresAdditionalFraudVerificationBasedOnUserHistory." Tiene 71 caracteres. También es cristal claro. Cuando ves esa variable en una declaración if, sabes exactamente qué se está comprobando y por qué. No se necesitan comentarios. No se requiere traducción mental.
El contraargumento que siempre escucho es "pero los nombres largos hacen que las líneas sean demasiado largas!" Claro, si todavía pretendes que estamos escribiendo código en terminales de 80 columnas de 1985. Ahora tenemos monitores de 27 pulgadas. Úsalos. Yo establezco mi límite de longitud de línea en 120 caracteres, y nunca he tenido un problema con la legibilidad.
Esta es la prueba que uso: si un desarrollador junior puede leer tu nombre de variable y saber inmediatamente lo que contiene, qué tipo es y aproximadamente para qué se usa, lo has nombrado correctamente. Si necesitan desplazarse hacia arriba para ver dónde fue declarado o verificar la definición de tipo, has fallado.
He visto esto mejorar dramáticamente la calidad de la revisión de código. Cuando los nombres son claros, los revisores pasan menos tiempo preguntando "¿qué hace esto?" y más tiempo preguntando "¿es este el enfoque correcto?" Ahí es donde está el verdadero valor.
Regla que Sigo #3: Los Comentarios Explican el Por Qué, No el Qué (Pero Usa Más de lo que Piensas)
Los puristas del código limpio te dirán que "el buen código no necesita comentarios." Tienen medio razón. El buen código no necesita comentarios que expliquen qué hace el código. Pero definitivamente necesita comentarios que expliquen por qué existe el código.
| Regla de Código Limpio | Lo que Dicen los Libros | Lo que Realmente Funciona | Cuándo Romperla |
|---|---|---|---|
| Longitud de la Función | Mantén las funciones por debajo de 20 líneas | Mantén las funciones por debajo de una pantalla (40-60 líneas) | Cuando dividir crea más confusión que claridad |
| Comentarios | El código debe ser auto-documentable | Explica por qué, no qué | Algoritmos complejos, reglas de negocio o decisiones no obvias |
| Principio DRY | Nunca te repitas | No te repitas aún (espera a la tercera ocurrencia) | Cuando la abstracción acopla características no relacionadas |
| Nombres de Variables | Siempre usa nombres descriptivos | El contexto importa: 'i' está bien en bucles, 'userAuthenticationToken' en ámbitos pequeños es excesivo | Contadores de bucles, abreviaturas bien conocidas en contexto de dominio |
El mes pasado, encontré una función en nuestra base de código que tenía una solución bizarra: estaba agregando un retraso de 50 milisegundos antes de procesar un webhook. Sin comentario. Sin explicación. Solo "await sleep(50);" ahí sentado como una mina terrestre. Pasé dos horas tratando de averiguar si era un error o intencionado. Resulta que era una solución temporal para una condición de carrera en una API de terceros que descubrimos después de tres días de depuración en producción.
Ahora ese código tiene un comentario: "// retraso de 50ms requerido: el webhook de Stripe puede llegar antes de que su API refleje el estado del cargo. Descubierto durante el incidente #2847 el 2023-08-15. Eliminar esto después de que Stripe solucione su problema de consistencia eventual (ticket #45892)."
🛠 Explora Nuestras Herramientas
Ese es un buen comentario. Explica por qué existe el código, hace referencia al incidente que lo causó e incluso proporciona una ruta para eliminarlo en el futuro. Sin ese comentario, el siguiente desarrollador lo habría eliminado pensando que era un error.
Agrego comentarios liberalmente en tres situaciones: cuando estoy trabajando alrededor de un error en una dependencia, cuando estoy implementando una regla de negocio no obvia y cuando estoy optimizando para rendimiento de una manera que hace que el código sea menos legible. En cada caso, el comentario explica el contexto que no es visible en el propio código.