💡 Key Takeaways
- 1. Names Should Reveal Intent, Not Require Archaeology
- 2. Functions Should Do One Thing and Do It Well
- 3. Comments Should Explain Why, Not What
- 4. Keep Your Code DRY, But Not Bone Dry
Por Marcus Chen, Ingeniero Principal de Software con 14 años construyendo sistemas escalables en empresas Fortune 500 y startups
💡 Puntos Clave
- 1. Los Nombres Deben Revelar la Intención, No Requerir Arqueología
- 2. Las Funciones Deben Hacer Una Cosa y Hacerla Bien
- 3. Los Comentarios Deben Explicar Por Qué, No Qué
- 4. Mantén Tu Código DRY, Pero No Demasiado Seco
Hace tres años, heredé una base de código que me hizo cuestionar mis elecciones de carrera. El equipo anterior había entregado características rápidamente—realmente rápido. Pero cuando abrí el archivo principal del servicio, encontré 4,200 líneas de lógica enredada, variables nombradas temp2 y finalFinal, y funciones que hacían diecisiete cosas diferentes. Una simple corrección de errores que debería haber tomado una hora consumió tres días. Ese proyecto me enseñó algo crucial: la velocidad sin disciplina crea deuda técnica que se acumula como el interés de una tarjeta de crédito al 29% APR.
Desde entonces, he hecho del código limpio mi obsesión. He refactorizado sistemas heredados que sirven a 50 millones de usuarios, he mentoreado a más de 80 desarrolladores y he visto equipos transformar su productividad al adoptar estos principios. Los datos son convincentes: los equipos que practican los principios de código limpio reducen la densidad de errores en un 40-60% y reducen el tiempo de incorporación para nuevos desarrolladores a la mitad. Más importante aún, lanzan características más rápido a largo plazo porque no están luchando constantemente contra su propia base de código.
El código limpio no se trata de ser pedante o seguir reglas por el mero hecho de hacerlo. Se trata de respeto—respeto por tu futuro yo, tus compañeros de equipo, y el próximo desarrollador que mantendrá tu trabajo a las 2 AM cuando la producción esté caída. Aquí están los diez principios que transformaron la forma en que escribo código y cómo los equipos que he liderado entregan software.
1. Los Nombres Deben Revelar la Intención, No Requerir Arqueología
La primera vez que revisé código en mi empresa actual, encontré una función llamada processData(). Me tomó 45 minutos entender lo que realmente hacía: validar la entrada del usuario, transformar valores de moneda, actualizar tres tablas de base de datos, enviar dos correos electrónicos diferentes y registrar eventos de análisis. El nombre no reveló nada sobre esta complejidad.
Un buen nombramiento es la base del código limpio porque leemos código mucho más de lo que lo escribimos. Los estudios muestran que los desarrolladores pasan el 58% de su tiempo leyendo y entendiendo código frente al 42% escribiendo o modificándolo. Cada nombre vago es un impuesto en ese tiempo de lectura, multiplicado por cada desarrollador que toca ese código.
Aquí está mi marco de nombramiento: un nombre de variable o función debe responder a tres preguntas sin requerir que leas su implementación. ¿Qué representa? ¿Qué hace? ¿Por qué existe? Una variable llamada d no responde ninguna de estas. Una variable llamada daysSinceLastModification responde las tres.
Para las funciones, sigo el patrón verbo-sustantivo religiosamente. getUserById() es claro. get() es inútil. handleUserData() es vago—¿manejar cómo? Para variables booleanas, uso predicados: isActive, hasPermission, canEdit. Estos se leen naturalmente en declaraciones condicionales: if (isActive && hasPermission) frente a if (active && permission).
He visto equipos desperdiciar cientos de horas porque alguien abrevió customer a cust en la mitad de la base de código y cstmr en la otra mitad. La consistencia importa enormemente. Establece convenciones de nombramiento temprano y hazlas cumplir a través de revisiones de código y reglas de linting. Tu futuro yo te lo agradecerá cuando estés depurando a medianoche y no tengas que descifrar lo que representa tmp_val_2.
Una técnica práctica que uso: si no puedo pensar en un buen nombre de inmediato, escribo un comentario describiendo lo que hace la variable o función, luego convierto ese comentario en un nombre. Si el nombre se vuelve demasiado largo (más de 4-5 palabras), eso generalmente es una señal de que la función está haciendo demasiado y necesita ser descompuesta.
2. Las Funciones Deben Hacer Una Cosa y Hacerla Bien
El Principio de Responsabilidad Única no es solo una teoría académica—es la diferencia entre un código mantenible y una pesadilla de mantenimiento. Aprendí esto por las malas cuando depuraba una función de 300 líneas que manejaba el registro de usuarios, la verificación de correos electrónicos, el procesamiento de pagos y el seguimiento de análisis. Encontrar el error tomó seis horas. Solucionarlo tomó cinco minutos.
"La relación de tiempo que se pasa leyendo frente a escribiendo código es muy superior a 10 a 1. Estamos constantemente leyendo código antiguo como parte del esfuerzo para escribir nuevo código. Hacer que sea fácil de leer hace que sea fácil de escribir." — Robert C. Martin
Una función debe hacer una cosa, hacerla bien y hacer solo esa cosa. Pero, ¿qué cuenta como "una cosa"? Mi regla general: si no puedes describir lo que hace una función en una sola oración sin usar la palabra "y", está haciendo demasiado. validateUserInput() hace una cosa. validateUserInputAndSaveToDatabase() hace dos cosas y debería ser dividida.
Apunto a funciones que tienen de 10 a 20 líneas de largo. Algunos desarrolladores piensan que esto es extremo, pero las funciones pequeñas tienen enormes beneficios. Son más fáciles de probar—puedes verificar un comportamiento sin configurar escenarios complejos. Son más fáciles de reutilizar—las funciones pequeñas y enfocadas se convierten en bloques de construcción para operaciones más grandes. Son más fáciles de entender—puedes captar toda la función sin desplazarte.
Cuando refactorizo funciones grandes, busco costuras naturales donde el código cambia de nivel de abstracción. Una función que valida la entrada, transforma datos y guarda en una base de datos está operando en tres niveles diferentes. Extraigo cada nivel en su propia función: validateOrderData(), transformOrderForStorage(), y saveOrder(). La función original se convierte en un coordinador que llama a estas tres funciones en secuencia.
Este enfoque también hace que el manejo de errores sea más limpio. En lugar de bloques try-catch anidados que abarcan 50 líneas, cada pequeña función maneja sus propios errores adecuadamente. La función coordinadora puede entonces manejar escenarios de errores de alto nivel sin quedar atrapada en los detalles de implementación.
He medido el impacto de este principio en mis equipos. Después de adoptar límites estrictos de tamaño de función, nuestro tiempo promedio para corregir errores cayó de 4.2 horas a 1.8 horas. Los nuevos miembros del equipo se volvieron productivos un 40% más rápido porque podían comprender funciones individuales sin necesidad de comprender primero todo el sistema.
3. Los Comentarios Deben Explicar Por Qué, No Qué
Al principio de mi carrera, creía que un buen código significaba muchos comentarios. Escribiría cosas como // incrementar contador en 1 sobre counter++. Mi desarrollador senior me apartó y dijo algo que cambió mi perspectiva: "Si tu código necesita comentarios para explicar lo que hace, tu código no es lo suficientemente claro."
| Aspecto | Código Sucio | Código Limpio | Impacto |
|---|---|---|---|
| Nombres de Funciones | processData(), doStuff(), handleIt() | validateAndTransformUserInput(), sendWelcomeEmail() | Reduce el tiempo de comprensión en un 70% |
| Longitud de Funciones | 200-500+ líneas, múltiples responsabilidades | 10-20 líneas, responsabilidad única | Densidad de errores reducida en un 40-60% |
| Nombres de Variables | temp2, finalFinal, x, data | userEmailAddress, validatedOrderTotal | Tiempo de incorporación reducido a la mitad |
| Comentarios | Explicando qué hace el código | Explicando por qué se tomaron decisiones | Tiempo de mantenimiento reducido en un 50% |
| Duplicación de Código | Misma lógica copiada en más de 5 archivos | Extraído en funciones reutilizables | Cambios requieren 1 edición frente a 5+ |
Los comentarios deben explicar por qué tomaste una decisión, no qué hace el código. El código mismo debe ser autoexplicativo a través de una buena nomenclatura y estructura clara. Cuando veo // recorrer usuarios encima de un bucle for, eso es ruido. El bucle ya muestra que está recorriendo usuarios. Pero un comentario como // Usando búsqueda lineal aquí porque el array tiene típicamente 5-10 elementos y el costo de la búsqueda binaria no vale la pena—eso es valioso. Explica una decisión que no es obvia a partir del código mismo.
Utilizo comentarios para documentar reglas comerciales no obvias, explicar soluciones alternativas para errores de bibliotecas de terceros, o aclarar por qué no estamos utilizando la solución "obvia". Por ejemplo: // No se puede usar async/await aquí porque Safari 12 no lo soporta en los trabajadores de servicio y el 8% de nuestros usuarios aún están en Safari 12. Ese comentario previene que el siguiente desarrollador "arregle" algo que no está roto.
Los comentarios de advertencia son otro caso de uso legítimo. // ADVERTENCIA: Cambiar este tiempo de espera afecta la limitación de tasa en el procesador de pagos. Ver ticket #1234 antes de modificar. Esto previene que desarrolladores bien intencionados hagan cambios que tengan consecuencias inesperadas.