Cómo escribir mejores nombres para tus variables, funciones y clases – Con ejemplos

Nombrar es una de las partes más importantes y desafiantes de escribir código limpio, mantenible y escalable. Un nombre de variable bien pensado, por ejemplo, puede actuar como código autoexplicativo, ahorrando tiempo y esfuerzo en entender la lógica. Pero los nombres mal elegidos, por otro lado, pueden llevar a confusión y errores.

Este artículo servirá como una guía completa sobre cómo idear nombres significativos para nombres de clases, variables y funciones con ejemplos y mejores prácticas.

¿Por qué importa el nombre?

• Legibilidad: Los buenos nombres hacen que tu código sea intuitivo y reducen la curva de aprendizaje para otros.

• Mantenibilidad: Es más fácil refactorizar o depurar un código bien nombrado.

• Colaboración: Nombres claros mejoran la comunicación y la productividad en equipo.

• Escalabilidad: Los nombres significativos ayudan a mantener proyectos grandes manejables.

Diferentes Estilos de Convenciones de Nomenclatura

Los diferentes estilos de convenciones de nomenclatura son cruciales para mejorar la legibilidad y mantenibilidad del código en varios lenguajes de programación.

Estilos como camelCase, PascalCase, snake_case y kebab-case están adaptados a contextos y prácticas específicas.

camelCase es ampliamente utilizado para variables y funciones, mientras que PascalCase es preferido para clases. snake_case es un favorito en Python por su claridad, y kebab-case domina en CSS para el estilo de elementos HTML.

Cada estilo garantiza consistencia, haciendo que el código sea intuitivo para equipos y futuros desarrolladores. Aquí tienes una tabla de resumen rápido de algunas convenciones de nombres populares junto con sus casos de uso y ejemplos:

Cómo Elegir el Estilo Adecuado

1. Específico del Lenguaje: Sigue las convenciones de tu lenguaje de programación o framework. Por ejemplo:

   • JavaScript: camelCase para variables y funciones, PascalCase para componentes.

   • Python: snake_case para variables y funciones.

   • CSS/HTML: kebab-case para nombres de clases e IDs.

2. Estándares del Equipo o Proyecto: La consistencia es clave. Utiliza el estilo acordado para tu equipo/proyecto.

3. Específico para un Propósito: Utiliza estilos de nombramiento que representen mejor la entidad que se está nombrando (por ejemplo, constantes en SCREAMING_SNAKE_CASE).

Directrices Generales de Nomenclatura

Antes de adentrarnos en convenciones de nomenclatura específicas para nombres de clase, variables y funciones, exploremos algunos principios universales:

1. Ser descriptivo y conciso: Los nombres deberían transmitir el propósito o rol de la variable/función/etc:

    // Malo
    let x = 10;
   
    // Bueno
    let maxUsuariosPermitidos = 10;
   

2. Avoidar abreviaturas crípticas que podrían ser difíciles de entender para otros desarrolladores (o incluso para tu futuro yo):

    // Mal
    let usrNm = "John";
   
    // Bien
    let userName = "John";
   

3. Usar convenciones de nombrado consistentes: Elige un estilo de nombrado (camelCase, PascalCase, kebab-case, snake_case) y mantente con él a lo largo de tu proyecto.

4. Evita palabras clave reservadas o nombres confusos:

    // Malo
    let let = 5;
   
    // Bueno
    let nombreVariable = 5;
   

Bien, ahora que hemos cubierto lo básico, profundicemos en algunas convenciones de nombres útiles.

Cómo crear buenos nombres de clase

Los nombres de clase definen el comportamiento visual o estructural de los elementos en tu aplicación. Escribir nombres de clase claros asegura que tu HTML y CSS sean fáciles de entender y mantener.

1. Usa nombres descriptivos

Los nombres de clase deben describir el propósito del elemento, no su apariencia.

<!-- Malo -->
<div class="red-button"></div>

<!-- Bueno -->
<div class="primary-button"></div>

2. Sigue la metodología BEM (Bloque-Elemento-Modificador)

BEM es una convención popular para escribir CSS escalable y mantenible. Separa los componentes en:

• Bloque: Representa el componente (por ejemplo, tarjeta).

• Elemento: Representa los elementos secundarios del bloque (por ejemplo, tarjeta__titulo).

• Modificador: Representa variaciones del bloque o elemento (por ejemplo, tarjeta__titulo--resaltado).

Ejemplo:

<div class="card">
  <h1 class="card__title card__title--highlighted">Welcome</h1>
  <p class="card__description">This is a card component.</p>
</div>

3. Usa kebab-case

Los nombres de las clases CSS se escriben tradicionalmente en kebab-case para una mejor legibilidad.

<!-- Mal -->
<div class="primaryButton"></div>

<!-- Bien -->
<div class="primary-button"></div>

Cómo crear buenos nombres de variables

Las variables contienen datos y deben tener nombres significativos que describan lo que representan.

1. Usa Sustantivos para las Variables

Las variables suelen ser sustantivos porque representan entidades o datos.

// Mal
let a = "John";

// Bien
let userName = "John";

2. Usa Prefijos para Agregar Contexto

Agregar prefijos ayuda a aclarar el tipo o propósito de una variable:

• Boolean: es, tiene, puede

• Números: máx, mín, total

• Arrays: Usa formas en plural (por ejemplo, usuarios, elementos).

Ejemplo:

let isUserLoggedIn = true;
const maxUploadLimit = 5; // MB
const usersList = ["John", "Jane"];

3. Evita Nombres Genéricos

Avoid nombres como datos, valor o elemento a menos que sean necesarios.

// Mal
let data = 42;

// Bien
let userAge = 42;

Cómo Crear Buenos Nombres de Funciones

Las funciones realizan acciones, por lo que sus nombres deben reflejar la operación o proceso que ejecutan.

1. Usa Verbos para las Funciones

Las funciones están orientadas a la acción, por lo que sus nombres deben comenzar con un verbo:

// Mal
function userData() {
  // ...
}

// Bien
function fetchUserData() {
  // ...
}

2. Sé Específico Sobre la Funcionalidad

Los nombres de las funciones deben indicar lo que hacen.

// Malo
function handle() {
  // ...
}

// Bueno
function handleFormSubmit() {
  // ...
}

3. Usa Prefijos para la Intención

• Para manejadores de eventos: manejar, en

• Para utilidades: calcular, convertir, formatear

• Para operaciones de búsqueda: buscar, obtener, cargar

• Para setters y getters: establecer, obtener

Ejemplo:

function handleButtonClick() {
  console.log("Button clicked!");
}

function calculateDiscount(price, discountPercentage) {
  return price * (discountPercentage / 100);
}

Cómo Saber si un Nombre es Adecuado para una Variable, Función o Clase

Para entender si un nombre es adecuado para una variable, función o clase, es importante evaluarlo usando varios principios clave. Aquí tienes una guía para ayudarte a decidir si un nombre es apropiado y significativo en tu contexto de programación:

1. ¿Representa el Propósito?

Los nombres orientados a propósitos son la característica más importante de un buen nombre. Un nombre debe decirte inmediatamente qué representa o hace la variable, función o clase sin necesidad de leer comentarios adicionales o documentación.

Cómo evaluar:

Pregúntate: “Cuando leo este nombre, ¿puedo entender inmediatamente su propósito?”

Ejemplo:

• userAge es mejor que a porque userAge te dice qué representa la variable, mientras que a es demasiado ambiguo.

2. ¿Es lo Suficientemente Específico?

El nombre debe ser lo suficientemente específico para reflejar el papel exacto de la entidad en tu código. Nombres excesivamente genéricos como data o temp pueden ser confusos porque no proporcionan suficiente contexto.

Cómo evaluar:

Pregunta: “¿Es este nombre específico para lo que esta variable, función o clase representa en mi aplicación?”

Ejemplo:

• calculateTaxAmount() es mejor que calculate() porque es claro lo que la función está calculando.

3. ¿Sigue una Convención de Nombres Consistente?

La consistencia en las convenciones de nombres es vital. Cuando todos los miembros del equipo siguen las mismas convenciones, el código es más fácil de entender y navegar.

Cómo evaluar:

Pregunta: “¿Este nombre es coherente con las convenciones de nombrado utilizadas en el resto del proyecto?” Siga las pautas del proyecto, como:

• camelCase para variables y funciones (por ejemplo, userAge)

• PascalCase para clases (por ejemplo, UserProfile)

• UPPERCASE_SNAKE_CASE para constantes (por ejemplo, MAX_USERS)

Ejemplo:

• Si tu equipo sigue camelCase, userData es mejor que UserData.

4. ¿Evita la Ambigüedad?

Un buen nombre elimina la ambigüedad. No debe estar abierto a múltiples interpretaciones. Si puede significar cosas diferentes en diferentes contextos, llevará a confusión.

Cómo Evaluar:

Pregunte: “¿Alguien no familiarizado con la base de código podría interpretar erróneamente a qué se refiere este nombre?”

Ejemplo:

• En lugar de nombrar un booleano isValid, use isUserLoggedIn o isEmailVerified para que sea más claro qué se está comprobando.

5. ¿Es Fácil de Leer y Pronunciar?

Si bien no es estrictamente necesario, la facilidad de lectura y pronunciación puede mejorar la legibilidad y mantenibilidad general de tu código.

Cómo Evaluar:

Pregunta: “¿Es este nombre fácil de leer en voz alta y puedo entenderlo de un vistazo?”

Evita nombres largos y utiliza abreviaturas comunes solo cuando sean ampliamente aceptadas.

Ejemplo:

• maxRetries es mejor que maximumNumberOfAttemptsToReconnect.

6. ¿Evita la Redundancia?

Evita la redundancia en los nombres. No repitas información que ya está implícita o descrita por el contexto.

Cómo Evaluar:

Pregunta: “¿Estoy repitiendo información que ya es clara a partir del contexto circundante?”

Ejemplo:

• Si tienes una clase llamada User, nombrar un método userGetData() es redundante. En su lugar, usa getData().

7. ¿Es Auto-Documentado?

Los mejores nombres se documentan solos. Buenos nombres reducen la necesidad de comentarios o explicaciones adicionales.

Cómo Evaluar:

Pregunta: “¿Este nombre describe completamente la variable, función o clase sin requerir un comentario que explique lo que hace?”

Ejemplo:

• La función calculateTotalPrice es autoexplicativa, por lo que no es necesario un comentario adicional como “Esta función calcula el precio total después del descuento.”

8. ¿Es contextual y relevante para el dominio?

El nombre debe encajar dentro del contexto de tu proyecto y su dominio. Por ejemplo, las convenciones de nombres para una aplicación web pueden diferir de las de una aplicación móvil o un modelo de aprendizaje automático.

Cómo evaluar:

Pregúntate: “¿Este nombre está alineado con el dominio y contexto de mi proyecto?”

Si estás trabajando en un dominio específico (por ejemplo, finanzas, salud, juegos), utiliza términos específicos del dominio que sean fácilmente reconocibles.

Ejemplo:

• En una aplicación de juegos, healthPoints es más apropiado que hp, ya que refleja su significado.

9. ¿Es a prueba de futuro?

Considera cómo evolucionará tu código. Los nombres deben ser lo suficientemente flexibles para adaptarse a cambios futuros sin necesidad de refactorización.

Cómo evaluar:

Pregúntate: “¿Este nombre seguirá teniendo sentido si cambia la funcionalidad o el proyecto crece?”

Ejemplo:

• userInfo podría quedar obsoleto si la estructura de datos cambia. Es mejor usar userProfile si esperas que se añadan más campos.

10. ¿Evita números mágicos y valores codificados en duro?

Números mágicos (números con un significado poco claro) deben evitarse a favor de constantes con nombres.

Cómo evaluar:

Preguntar: “¿Este nombre representa una constante significativa, o es solo un número en bruto?”

Ejemplo:

• En lugar de usar 1000, usar una constante como MAX_FILE_SIZE para explicar el significado detrás del número.

Ejemplos prácticos

Ejemplo de CSS

El siguiente ejemplo de CSS demuestra cómo aplicar convenciones de nomenclatura BEM (Bloque-Elemento-Modificador) para mantener una jerarquía de clases estructurada y escalable en tu hoja de estilos:

<!-- HTML -->
<div class="navbar">
  <ul class="navbar__list">
    <li class="navbar__item navbar__item--active">Home</li>
    <li class="navbar__item">About</li>
    <li class="navbar__item">Contact</li>
  </ul>
</div>

/* CSS */
.navbar {
  background-color: #333;
  padding: 10px;
}

.navbar__list {
  list-style: none;
}

.navbar__item {
  display: inline-block;
  padding: 10px;
}

.navbar__item--active {
  color: orange;
}

Esto es lo que está sucediendo en este código:

• Nomenclatura BEM: navbar es el Bloque, que representa el componente de navegación principal.

• navbar__list es el Elemento, un hijo del bloque, que representa la lista de elementos de navegación.

• navbar__item es otro Elemento que representa elementos individuales de la lista.

• navbar__item--active es un Modificador utilizado para resaltar el elemento del menú activo.
  Este enfoque facilita la comprensión de las relaciones y roles dentro del HTML y CSS, favoreciendo estilos modulares y reutilizables.

Ejemplo de JavaScript

Este ejemplo de JavaScript muestra cómo utilizar convenciones de nombres significativas y consistentes para variables y funciones para que el código sea autoexplicativo:

// Variables
let isUserLoggedIn = false;
const maxAllowedItems = 10;

// Funciones
function fetchUserDetails(userId) {
  // Obtener datos de usuario desde la API
}

function calculateTotalPrice(cartItems) {
  return cartItems.reduce((total, item) => total + item.price, 0);
}

Esto es lo que sucede en el código:

• Variables:

  • isUserLoggedIn: Una variable booleana nombrada claramente para indicar su propósito. Prefijar con is ayuda a identificarla como booleana.

  • maxAllowedItems: Una constante con el prefijo en mayúsculas max muestra que es un límite, dejando clara su intención.

• Funciones:

  • fetchUserDetails(userId): El nombre refleja el propósito de la función, que es recuperar detalles del usuario. El parámetro userId es descriptivo y evita ambigüedades.

  • calculateTotalPrice(cartItems): El nombre de la función establece explícitamente la acción realizada. El parámetro cartItems es relevante contextualmente para el dominio del comercio electrónico.

Por qué es bueno: Estas convenciones aseguran que el código sea legible e intuitivo, reduciendo la carga cognitiva para otros desarrolladores que trabajen en el mismo proyecto.

Conclusión

Un nombrado significativo es tanto una convención importante como una forma de arte que impacta significativamente en la legibilidad y mantenibilidad de tu código.

Intenta seguir estos principios básicos:

• Usa nombres descriptivos y concisos.

• Adhiérete a convenciones consistentes como BEM para nombres de clases y camelCase para variables y funciones.

• Usa prefijos para agregar contexto y claridad.

Estos y otros consejos que hemos discutido aquí harán que tu código sea un placer de trabajar, ya sea que lo revisites meses después o colabores con un equipo. Comienza a aplicar estos consejos hoy y observa cómo la calidad de tu código se eleva.