⏱ Tiempo de lectura estimado: 7 minutos

Clean Code: cómo nombrar variables sin perder la cordura

Hay un momento en la vida de todo dev en el que abres un archivo que escribiste hace seis meses y te encuentras con algo como data2, tempVal o, mi favorito personal, x2. Y te quedas ahí, mirando la pantalla, preguntándote qué diablos estabas pensando.

Eso no es un problema de memoria. Es un problema de nombres. Y aunque nombrar cosas parece trivial —es solo texto, ¿no?— en la práctica es una de las decisiones más impactantes que tomamos como programadores. Un buen nombre puede ahorrarte 20 minutos de debugging. Uno malo puede costarte una tarde entera y una discusión con tu equipo.

Vamos al grano.

Por qué los nombres malos cuestan más de lo que crees

El código se lee muchas más veces de las que se escribe. Eso lo sabe todo el mundo, pero pocos lo interiorizan de verdad hasta que les toca revisar un PR de alguien más (o el suyo propio) y tienen que rastrear qué hace handleData() en una función de 80 líneas.

En mi experiencia, los nombres vagos generan un problema en cadena: primero no entiendes qué hace la variable, luego no entiendes el bloque de código, luego no entiendes la función, y de repente estás leyendo cinco archivos distintos para descifrar algo que debería haber sido obvio desde el principio.

El punto es que un mal nombre no solo confunde. Ralentiza. Y en un equipo, eso se multiplica por cada persona que toca ese código.

El síndrome de data, info y temp

Estos tres son los grandes culpables. Son nombres que dicen absolutamente nada sobre el contenido o el propósito. data es especialmente traicionero porque parece razonable en el momento —claro, es data— pero cuando tienes data, data2 y userData en el mismo componente, el caos está servido.

Algo que me ha funcionado es hacerme una pregunta simple antes de nombrar algo: ¿qué contiene esto y para qué se usa? Si la respuesta es larga, probablemente el nombre también debería serlo. filteredActiveUsers es más largo que data, sí. Pero dentro de tres meses te vas a agradecer a ti mismo.

Las reglas no escritas de los buenos nombres en clean code

Sé específico, no exhaustivo

Hay un equilibrio. listOfAllActiveUserAccountsWithPremiumSubscription es demasiado. users es demasiado poco. activePremiumUsers es justo. La especificidad tiene que ser proporcional al contexto: si estás en una función que solo maneja usuarios premium, users puede ser suficiente. Si conviven varios tipos de usuarios, necesitas ser más explícito.

Ojo que el contexto importa mucho. Una variable llamada index dentro de un bucle corto está perfecta. La misma variable en una función de 100 líneas con tres bucles anidados es una bomba de tiempo.

Los booleanos merecen su propio apartado

Nombrar booleanos mal es un arte. He visto cosas como active, status, flag o el clásico check. Ninguno de esos te dice si el valor es verdadero o falso, ni qué significa que lo sea.

La convención que más sentido me hace: los booleanos deberían poder leerse como una pregunta con respuesta de sí o no. isActive, hasPermission, canEdit, shouldRefetch. Cuando lees if (isActive) en voz alta, suena a lenguaje humano. Cuando lees if (active), suena a... nada en particular.

Funciones: verbos que describen la acción, no el resultado

Una función hace algo. Su nombre debería reflejar esa acción. getUserData() es pasable, pero fetchUserProfile() es mejor porque te dice cómo obtiene los datos (fetch implica una llamada asíncrona, probablemente a una API). calculateTotalWithTax() es mejor que getTotal() porque te dice que hay un cálculo involucrado, no solo una lectura.

Ahora bien, si tu función se llama processAndValidateAndSaveUser(), el problema no es el nombre. El problema es que la función hace demasiadas cosas. El nombre te está avisando.

Errores comunes que todos cometemos (y cómo salir de ellos)

Abreviar por abreviar

btn, usr, cfg, mgr. Sé que parece eficiente. No lo es. Los editores modernos tienen autocompletado. Nadie necesita escribir button completo más de una vez. Pero todos necesitan leerlo completo muchas veces.

Las únicas abreviaciones que se justifican son las que son universalmente conocidas en el contexto: id, url, html, api. Esas están bien. usr para user no tiene ningún sentido en 2024.

Nombres que mienten

Esto es peor que un nombre vago: un nombre que activamente te engaña. Una función llamada getUser() que no solo obtiene el usuario sino que también lo registra en un log y actualiza un timestamp. O una variable llamada userList que en realidad es un objeto con metadata y una lista anidada.

Cuando el nombre no coincide con el comportamiento, el lector asume lo que dice el nombre y se lleva una sorpresa desagradable. Eso genera bugs difíciles de rastrear porque nadie sospecha de algo que cree entender.

El miedo a los nombres largos

Este viene de los tiempos en que la memoria era cara y los lenguajes tenían límites de caracteres. Hoy no hay excusa. calculateMonthlyRevenueByRegion es un nombre perfecto. No es largo, es preciso.

Dicho esto, si sientes que el nombre necesita ser una oración completa para ser descriptivo, probablemente la abstracción está mal planteada. Ahí es cuando vale la pena detenerse y repensar la estructura del código, no solo el nombre.

Un ejercicio concreto para mejorar desde hoy

La próxima vez que escribas una variable o función, antes de continuar, hazte estas tres preguntas:

¿Qué contiene o hace exactamente? No en términos abstractos, sino concretos. No "maneja usuarios", sino "filtra usuarios con suscripción activa".

¿Alguien que no conozca este contexto lo entendería? Si tienes que explicarlo en un comentario, el nombre no es suficientemente bueno.

¿El nombre sigue siendo válido si el código cambia un poco? Los nombres demasiado específicos a una implementación concreta se vuelven mentirosos cuando refactorizas. Busca el equilibrio entre descriptivo y flexible.

No es un proceso rápido al principio. Pero como cualquier hábito técnico, se vuelve automático con la práctica.

Antes de irte

Leer código elegante ajeno y luego mirar el tuyo puede desanimar. Ver ese PR con nombres perfectos, funciones de cinco líneas y cero comentarios explicativos hace que el propio código parezca un desastre. Pero ese contraste es exactamente cómo se aprende, y la mayoría de ese código elegante también pasó por versiones horribles antes de llegar ahí.

La próxima variable que nombres un poco mejor que la anterior ya es progreso real. El clean code no es un destino, es una dirección.