⭐ Javascript buenas prácticas: Nombres

Ricardo Ortega Chap — Thu, 31 Oct 2024 20:18:54 +0000

🚀 Tabla de contenido

Cambiando el chip.
Nombres descriptivos.
Convención para nombrar variables.
Cuídate de estas prácticas.
Nombres descriptivos basados en el propósito del tipo.
- Matrices (arrays)
- Booleanos (booleans)
- Funciones (functions)
- Clases (class)
🔒 Mini guía de estilos para JS
🔒 Mejorando la Legibilidad con ES6+

Bienvenido, al primer registro en la 🚀 Bitácora del capitán Dev: Nombres (Naming). Y Recuerda, tomarte el tiempo para nombrar de forma descriptiva no es un detalle menor en tu brújula.

🚀 Cambiando el chip

Hacer cambios en un código “con mal olor” es realmente 💔cardíaco, especialmente cuando se trata de código de terceros. Y no me dejarás mentir, nada te hace cuestionar más tus decisiones de vida que leer tu propio código de hace siete días y pensar: “¿Cómo es que no fui despedido por esto?”

En lugar de avanzar y hacer mejoras🚀, te ves obligado a detenerte y luchar para comprender lo que está frente a ti, intentando descifrar lo que alguien más dejó atrás. Es una experiencia frustrante que drena tu ⌛ tiempo y ⚡ energía, robándote la satisfacción de la creación.

El código con mal olor (code smells) suele ser el resultado de la prisa por cumplir entregas, la falta de experiencia en buenas prácticas y la sobrecarga de trabajo, lo que lleva a priorizar soluciones rápidas sobre las correctas. Esto acumula deuda técnica, reforzada por la mentalidad de "con que funcione basta", ignorando el alto costo de mantener código desorganizado a largo plazo.

Y recuerda, lo que he compartido aquí son solo recomendaciones💡; no pretendo imponerte nada. Toma lo que mejor se adapte a ti o a tu equipo 🤝 y hazlo tuyo✨.

Javascript sin olores

Cuando hablo de "JavaScript sin olores", no me refiero a que tu código deba oler a ☕ café recién hecho, pero sí a que sea claro y no intimide a quien lo lea 👀. En este artículo, de la mano de JavaScript, el único lenguaje del lado del cliente y a menudo el más incomprendido, exploraremos y aprovecharemos las bondades de ES6+ junto con convenciones, guías de estilo y patrones para escribir código limpio, moderno y fácil de mantener ✨.

Sin más vueltas, a lo que venimos.

🪐 Nombres descriptivos

Esto significa que los nombres de variables, funciones, clases y constantes explican claramente su propósito y contenido sin necesidad de comentarios adicionales.

Nombrar de forma descriptiva puede parecer una acción pequeña, pero es el primer y más importante paso para fijar una dirección y la más clara. Este simple hábito reduce significativamente la carga cognitiva y mejora la legibilidad y claridad de tu código.

Y ¡por favor!, olvídate de los nombres genéricos y acrónimos difíciles de entender.

// Evita esto ❌ o naufragarás.
let cic = 5;
let p = 1051;
const abUrl = 'https://api.myecommerce.com/v1';
function valOrder() {}
class prod {}

Como puedes ver, el propósito de cada variable es un misterio digno de Sherlock Holmes🕵️‍♂️. ¿Por qué? Porque para descifrar qué hacen, necesitarías un montón de contexto extra, como comentarios que no existen, horas 🔍 revisando dónde demonios se usan, o tener al programador a mano, como si fuera tu propio servicio de soporte técnico.

// Bien ✅
let cartItemCount = 5;
let cartTotalPrice = 1051;
const API_BASE_URL = 'https://api.myecommerce.com/v1';
function validateOrder() {}
class Product {}
let shipName = 'Barco fantasma';

En este caso, las variables reflejan claramente su contenido y propósito:

cartItemCount: Número de productos en el carrito de compras.
cartTotalPrice: Precio total de todos los productos en el carrito.
API_BASE_URL: Contiene la URL base de la API utilizada para realizar solicitudes en la aplicación.
validateOrder: Es una función que probablemente válida si un pedido es correcto antes de ser procesado.
Product: Es una clase que representa un producto.

🪐 Convención para nombrar variables

En el mundo de los lenguajes de programación existen varias convenciones ampliamente utilizadas al nombrar variables, entre las más comunes están las sigs.:

UpperCamelCase
PascalCalmelCase
snake_case
SCREAMING_SNAKE_CASE
flatcase
dot.notation

En el caso de JavaScript, la recomendación tanto por la comunidad de desarrolladores como por el equipo que mantiene el lenguaje es:

lowerCamelCase

Y es la única que nos interesa destacar en este momento. En esta convención lowerCamelCase cada palabra comienza con minúscula, excepto las subsecuentes, que inician con mayúscula.

Cartitemcount = 10; // ❌
cartItemCount = 10; // ✅ Bien

🪐 Convenciones para nombrar constantes (const)

En JavaScript, las constantes pueden almacenar distintos tipos de datos o referencias. Tener claro el contenido que pueden almacenar te permitirá asignar un nombre descriptivo y que grite su propósito, mejorando así la legibilidad del código.

Datos que pueden almacenar las constantes:

Valores primitivos → (string, number, boolean, null, undefined, bigint, symbol).

Estructuras complejas → (arrays, objetos, funciones).

Referencias a elementos del DOM → (Element, NodeList, etc.).

Cómo te pudiste dar cuenta, las constantes no solo se limitan a almacenar valores primitivos o estructuras complejas; también pueden contener referencias que apuntan a elementos del DOM.

Ahora que conocemos los diferentes tipos de valores o referencias que las constantes pueden almacenar, hablemos de las convenciones para nombrarlas.

SCREAMING_SNAKE_CASE

Se utiliza principalmente para valores globales.

¿Cuándo usar?

Cuando el valor no cambia durante la ejecución del programa.
Para valores que representan configuraciones, claves de API, constantes matemáticas, etc.
Cuando se quiere indicar claramente que el valor es una constante global.

const API_BASE_URL = 'https://api.myecommerce.com/v1';
const PROMO_DISCOUNT_RATE = 0.10;
const MAX_LOGIN_ATTEMPTS = 5; // Número máximo de intentos de inicio de sesión.
const PI = 3.14159; // Valor de π.

lowerCamelCase

Se emple para constantes cuyo valor sera local dentro del código.

¿Cuándo usar?

Para constantes locales dentro de funciones o bloques de código.
Para valores que no son estrictamente inmutables, sino que simplemente no deberían cambiar después de ser asignados.

const userProfile = { name: "Alice", age: 30 }; // Objeto con información del usuario.
const h1El = document.getElementById('js-mainTitle'); // Elemento del DOM donde solo se modifica sus propiedades pero no la referencia.
h1El.textContent // 'Mi ecommerce'
h1El.textContent.toUpperCase() // 'MI ECOMMERCE'
const productDetails = { id: 123, name: "Zapatillas deportivas", price: 49.99 }; // Información de un producto devuelta por una API.

Convenciones para nombrar constantes del DOM

Ahora es importante mencionar que cuando almacenamos o hacemos referencia a un elemento del DOM, lo que realmente solemos modificar son sus propiedades, como textContent, classList o estilos CSS, pero rara vez la referencia en sí. Por esta razón, utilizar const en lugar de let. Esta es una convención común al trabajar con elementos del DOM. Sin embargo, esto no es una regla estricta: si en algún momento necesitas usar let, hazlo siempre que se ajuste mejor a tus necesidades.

Existen dos convenciones principales que ayudan a identificar rápidamente que una constante almacena un elemento del DOM:

Sufijo el: Añadir el sufijo al final del nombre de la constante facilita reconocer que la variable representa un nodo del DOM. Esta práctica es especialmente útil para mejorar la legibilidad del código.

Esto quiere decir que una contante local que almacene un elemento del DOM, seguira la sig. nomenclatura de nombrado: lowerCalmelCase más el sufijo el.

const addToCartButtonEl = document.getElementById('add-cart');
const productListEl = document.getElementById('product-list');
const toggleMenuButtonEl = document.getElementById('toggle-menu');

Prefijo $: Similar a la convención utilizada en jQuery, este prefijo indica que la constante hace referencia a un elemento del DOM. En esta convención se agregara el simbolo $ al inicio de la palabra seguido de la convecion lowerCalmelCase.

const $article = document.createElement('ARTICLE');

Ambas convenciones son válidas y cumplen el mismo propósito: identificar claramente que la constante almacena un nodo del DOM. Lo más importante es elegir una y aplicarla consistentemente en tu proyecto

🪐 Como no nombrar (cuídate de estas practicas).

La siguientes practicas causan errores en la ejecución del código, así que tu variables:

No pueden incluir espacios en blanco.

let cart item count; // ❌ Mal

No pueden ser palabras reservadas del lenguaje.

// Como function, class, var, const, if, while, etc.
let function = 5; // ❌ Mal
let class = null;    // ❌ Mal

No pueden comenzar con números, aunque sí incluirlos después de la primera letra.

let 2cartItemCount = 6;  // ❌ Mal
let cartItemCount2 = 6;  // ❌ Mal, no genera error, pero evitar. números.

No pueden contener signos de puntuación, con la excepción de los signos $ y _.

let !cartItemCount;  // ❌ Mal
let ?cartItemCount  // ❌ Mal

No pueden contener operadores aritméticos ni otros símbolos alfanuméricos.

let cartI+temCount;  // ❌ Mal
let año = 2024;      // ❌ Mal, no genera error pero evitar.

Evitar usar guiones bajos y normales.

let cart-item-count; // ❌ Mal

Nota: La única excepción a la regla, es cuando se usa para nombrar constantes.

🪐 Nombres descriptivos basados en el propósito del tipo

Matrices (arrays)

Cuando guardes listas de cosas, usa nombres en plural.

let cartItems = [  // ✅ Bien 
    { id: 1, name: 'Laptop', quantity: 1, price: 999.99 },
    { id: 2, name: 'Mouse', quantity: 2, price: 25.99 }
];

let categories = ['Electronics', 'Home Appliances', 'Books'];  // ✅ Bien

Booleanos (booleans)

Imagina una caja llena de switches y ninguno dice si está encendido o apagado🔌. Darle prefijos como is, has, o can a tus variables booleanas es como etiquetar esos switches: isActive, hasPermission, canFly. ¡Sabes lo que hace cada uno al instante! ⚡️. Te ayudan a identificar rápidamente que se trata un valor booleano.

Por ejemplo, si necesitas una variable para verificar si se puede aplicar un descuento a un producto, un buen nombre sería canApplyDiscount.

let pendingOrders = true; // ❌ Mal
let hasPendingOrders = true; // ✅ Bien

let userAdmin = true; // ❌ Mal
let isUserAdmin = true; // ✅ Bien

let applyDiscount = true; // ❌ Mal
let canApplyDiscount = true; // ✅ Bien

Evita las negaciones

En lugar de nombrar una variable como isNotUserAdmin, utilice isUserAdmin. Siempre debes abordar la convención de nombres desde el lado positivo.

Veámoslo más claro en el sig. ejemplo. Entre estos nombres, ¿cuál te resulta más cómodo: isVisible o isInvisible?

!isVisible    // ✅ Bien, simple, evitamos la carga cognitiva.
!isInvisible  // ❌ Mal, innecesariamente complejo.

A continuación más ejemplos.

Bien ✅	Mal ❌
isOpen	isClosed
isVisible	isInvisible, isHidden, isShowing, show, hide
isResolved	isRejected
isRight, isGood	isWrong, isLeft, isBad
hasValue	isEmpty
isDefined	isUndefined
isOwner	isOwning, own, wasOwner, willBeOwner

Funcione (functions)

Para las funciones se recomienda usar camelCase y comenzar con un verbo que indique la acción que realiza la función.

Además de eso, debes usar sustantivos descriptivos como prefijos. Por ejemplo, si declaramos una función para recuperar un nombre, el nombre de la función debe ser getName.

function getProductDetails(productId) {
  // Obtiene los detalles de un producto por su ID
}

function addToCart(productId, quantity) {
  // Agrega un producto al carrito
}

function deleteProduct(productId) {
  // Elimina un producto del catálogo
}

function sendOrderConfirmationEmail(orderId, userEmail) {
  // Envía un correo de confirmación de pedido
}

En cada caso:

El verbo indica la acción (get, add, delete, send).
El sustantivo define la entidad sobre la que se actúa (ProductDetails, Cart, Product, OrderConfirmationEmail).
Clases (class)

Para las clases se recomienda usar PascalCase y nombrarlas con un sustantivo en singular que represente una entidad o concepto del dominio. Un buen nombre de clase responde a la pregunta: ¿Qué representa esta clase?

Además de eso, debes evitar prefijos o sufijos innecesarios. Por ejemplo, si modelamos un producto en un eCommerce, el nombre de la clase debe ser Product, en lugar de ProductClass o Products.

Usar PascalCase para clases y funciones constructoras.

class Product {
  constructor(name, price) {
    this.name = name;
    this.price = price;
  }

  getPriceWithTax(taxRate) {
    return this.price * (1 + taxRate);
  }
}

Si este contenido te inspiró, te identificaste o te aportó valor, compártelo que este es el primer registro en la Bitacora del capitan Dev y mantente cerca que seguiré creando más contenido como este para ayudarte a mejorar la calidad de tú y que no solo Skynet lo entienda.

DEV Community: Ricardo Ortega Chap