Convenciones de Nombres en JavaScript: Guía Completa
Aprende las convenciones de nombres estándar para variables, funciones, clases y constantes en JavaScript para código legible y mantenible.
TL;DR - Resumen rápido
- Usa camelCase para variables y funciones (ej: usuarioActivo, calcularTotal)
- Usa PascalCase para clases y constructores (ej: Usuario, Calculadora)
- Usa UPPER_SNAKE_CASE para constantes inmutables (ej: MAX_REINTENTOS, API_KEY)
- Usa nombres en plural para arrays y colecciones (usuarios, productos)
- Usa prefijos 'handle' para handlers y 'on' para callbacks (handleClick vs onClick)
- Evita abreviaciones y nombres genéricos - elige nombres descriptivos y específicos
Introducción a las Convenciones de Nombres
Las convenciones de nombres son uno de los aspectos más importantes para escribir código legible y mantenible. En JavaScript, seguir convenciones consistentes ayuda a otros desarrolladores (y a tu yo del futuro) a entender rápidamente qué hace cada parte del código sin necesidad de leer cada línea en detalle. Un buen nombre debe ser descriptivo, preciso y seguir los estándares establecidos por la comunidad.
JavaScript no impone reglas estrictas de nombres, pero la comunidad ha establecido convenciones que se han convertido en estándares de facto. Estas convenciones no son solo estéticas: mejoran la legibilidad, facilitan el mantenimiento y reducen la probabilidad de errores causados por confusión sobre el propósito de una variable o función.
- Mejora la legibilidad del código para ti y otros desarrolladores
- Facilita el mantenimiento y refactorización del código
- Reduce la necesidad de comentarios explicativos
- Ayuda a identificar rápidamente el tipo de dato o propósito
- Sigue los estándares de la comunidad JavaScript
Convenciones para Variables
Las variables en JavaScript deben seguir la convención camelCase, donde la primera palabra comienza con minúscula y cada palabra subsiguiente comienza con mayúscula. Esta convención es universal en JavaScript y se aplica tanto a variables declaradas con var, let como const (para variables mutables). El nombre debe ser descriptivo y representar claramente qué contiene la variable.
camelCase: La Convención Estándar
La convención camelCase es la forma preferida de nombrar variables en JavaScript. El primer carácter es siempre minúscula, y cada palabra subsiguiente comienza con mayúscula. Esto crea un patrón visual que es fácil de escanear y distingue las variables de otros constructos del lenguaje.
El ejemplo muestra la diferencia entre nombres de variables malos y buenos. Los nombres malos como x, n, o data no proporcionan ninguna información sobre su propósito. Los nombres buenos como nombreUsuario, edadPersona y listaProductos describen exactamente qué contienen, haciendo el código autodocumentado y más fácil de entender.
Nombres que cuentan una historia
Un buen nombre de variable debe responder a las preguntas: ¿qué es? ¿para qué sirve? ¿qué representa? Por ejemplo, en lugar de usar data o info, usa nombres específicos como usuarioRegistrado, listaTareas o resultadoCalculo.
Variables Booleanas
Las variables booleanas tienen una convención especial: deben comenzar con prefijos que indiquen su naturaleza de verdadero/falso. Los prefijos más comunes son is, has, can, should y will. Esto hace inmediatamente claro que la variable representa un estado o condición.
Los prefijos para variables booleanas transforman nombres ambiguos en claros indicadores de estado. isActive es más claro que active porque indica explícitamente que es una condición. hasPermission comunica que estamos verificando la existencia de un permiso. Estos prefijos ayudan a evitar confusiones sobre si una variable es un valor o una condición.
Convenciones para Funciones
Las funciones en JavaScript también siguen la convención camelCase, pero con una diferencia importante: deben comenzar con un verbo que describa la acción que realizan. Esto distingue las funciones de las variables y hace inmediatamente claro que invocar ese nombre ejecutará una acción. Los verbos más comunes incluyen get, set, calculate, validate, handle, create, update y delete.
Verbos de Acción para Funciones
Las funciones deben nombrarse con verbos que describan claramente qué hacen. Esto sigue el patrón de "acción + objeto" donde el verbo indica la operación y el resto del nombre indica sobre qué se opera. Esta convención hace el código más legible y predecible.
Los ejemplos demuestran cómo los verbos de acción hacen el propósito de las funciones inmediatamente claro. obtenerUsuario indica que la función recupera datos, validarEmail sugiere una operación de verificación, y calcularTotal implica un cálculo matemático. Esta consistencia permite leer el código como si fuera una narrativa en lenguaje natural.
Verbos comunes por categoría
Obtener datos: get, fetch, retrieve, find
Establecer datos: set, update, modify, change
Crear/eliminar: create, add, insert, delete, remove
Validación: validate, check, verify, ensure
Cálculo: calculate, compute, process, transform
Funciones Handler y Callbacks
Las funciones que manejan eventos, callbacks o operaciones asíncronas comúnmente usan el prefijo handle para la definición de la función. Esta convención indica que la función responde a un evento o condición específica, y ayuda a distinguirlas de funciones que realizan acciones directas.
El prefijo handle es especialmente útil en código que maneja eventos del DOM, promesas o operaciones asíncronas. handleClick indica que la función responde a un clic, handleSubmit maneja el envío de un formulario, y handleError gestiona situaciones de error. Esta convención hace el flujo de control más evidente.
Para callbacks que se pasan como props o parámetros, es común usar el prefijo on en lugar de handle. Esto distingue entre la función que ejecuta la acción (handle) y la prop que recibe el callback (on). Por ejemplo, onClick es la prop que recibe la función, mientras que handleClick es la función que maneja el evento.
Esta distinción entre handle y on es especialmente importante en componentes y funciones que aceptan callbacks. onSuccess, onError, onComplete indican que son callbacks que serán invocados cuando ocurra cierto evento, mientras que handleSuccess, handleError, handleComplete son las implementaciones concretas de esos callbacks.
Convenciones para Clases
Las clases en JavaScript deben seguir la convención PascalCase, donde cada palabra comienza con mayúscula. Esta convención distingue las clases de las variables y funciones, y es un estándar universal en JavaScript y otros lenguajes orientados a objetos. Los nombres de clases deben ser sustantivos que representen entidades o conceptos.
PascalCase para Clases y Constructores
PascalCase es la convención estándar para clases en JavaScript. Cada palabra comienza con mayúscula, sin espacios ni guiones. Esto crea una distinción visual clara entre clases (PascalCase) y variables/funciones (camelCase), lo que ayuda a identificar rápidamente constructores y tipos de objetos.
Las clases Usuario, Producto y Pedido representan entidades del dominio con nombres claros y descriptivos. El uso de PascalCase hace inmediatamente evidente que estos son constructores y no variables ordinarias. Esta distinción es especialmente importante en código que mezcla instancias con definiciones de clases.
Advertencia sobre instanciación
Siempre usa la palabra clave new al instanciar una clase. Omitir new en una clase no generará un error en JavaScript, pero creará un comportamiento inesperado donde this apunta al objeto global o undefined en modo estricto.
Métodos y Propiedades Privadas
Para métodos y propiedades que deben ser privadas, JavaScript moderno (ES2022+) introduce la sintaxis # para campos privados verdaderos. Sin embargo, muchos desarrolladores todavía usan el prefijo _ (guion bajo) como convención para indicar que un método o propiedad es privado por convención, aunque técnicamente sigue siendo accesible.
La sintaxis # crea campos verdaderamente privados que no son accesibles fuera de la clase, mientras que el prefijo _ es solo una convención que indica que el método o propiedad no debe usarse fuera de la clase. Ambas convenciones son válidas: usa # para privacidad real y _ cuando necesites acceso externo ocasional o para compatibilidad con código legacy.
Convenciones para Constantes
Las constantes en JavaScript siguen la convención UPPER_SNAKE_CASE, donde todas las letras son mayúsculas y las palabras se separan con guiones bajos. Esta convención indica que el valor no debe cambiar después de su asignación, y es especialmente común para valores de configuración, límites y claves de API.
UPPER_SNAKE_CASE para Constantes
La convención UPPER_SNAKE_CASE usa todas las letras mayúsculas con guiones bajos separando las palabras. Esto crea una distinción visual clara que indica que el valor es inmutable por convención. Aunque const en JavaScript no garantiza inmutabilidad profunda, esta convención comunica la intención de que el valor no debe ser reasignado.
Las constantes MAX_REINTENTOS, API_KEY y URL_BASE representan valores de configuración que no deberían cambiar durante la ejecución del programa. La convención UPPER_SNAKE_CASE hace evidente que estos son valores constantes, ayudando a prevenir modificaciones accidentales.
Es importante notar que no todas las variables declaradas con const necesitan UPPER_SNAKE_CASE. Usa esta convención solo para constantes verdaderas globales o de configuración que representan valores inmutables conocidos en tiempo de compilación. Para const locales que simplemente no son reasignadas, usa camelCase normal. Por ejemplo, const usuarioActual es preferible a const USUARIO_ACTUAL si es una variable local.
Nombres Descriptivos y Significativos
Más importante que la convención específica es elegir nombres que sean descriptivos y significativos. Un buen nombre debe explicar el propósito de la variable o función sin necesidad de comentarios adicionales. Evita abreviaciones, nombres genéricos y términos técnicos que no aporten información relevante.
Evitar Abreviaciones
Las abreviaciones pueden ahorrar algunos caracteres al escribir, pero cuestan mucho tiempo en lectura y comprensión. Es mejor escribir el nombre completo que dejar que otros desarrolladores (o tú mismo en el futuro) tengan que descifrar qué significa usr, cnt, tmp o msg.
La comparación muestra claramente cómo las abreviaciones oscurecen el propósito del código. usr vs usuario, cnt vs cantidad, tmp vs temporal. Los nombres completos son más largos pero infinitamente más claros. El código se lee muchas más veces de las que se escribe, así que invierte en nombres claros.
Nombres Específicos vs Genéricos
Los nombres genéricos como data, info, item o value no proporcionan información útil sobre qué contienen. Es mejor usar nombres específicos que describan exactamente qué representa el dato. Esto reduce la carga cognitiva al leer el código y hace más fácil identificar bugs.
Los nombres específicos como usuario, precio, productos y total describen exactamente qué representa cada valor. En contraste, data, info, item y value son tan genéricos que obligan al lector a buscar el contexto para entender qué contienen. Los nombres específicos hacen el código autodocumentado.
Excepciones a nombres específicos
Los nombres genéricos son aceptables en contextos muy específicos donde el tipo es obvio, como en funciones de orden superior (map, filter, reduce) donde item o element son estándar y el contexto del array proporciona la información necesaria.
Arrays y Colecciones: Singular vs Plural
Para arrays, listas y colecciones de elementos, usa nombres en plural que indiquen que la variable contiene múltiples valores. Esto hace inmediatamente claro que estás trabajando con una colección. En callbacks de métodos de arrays, usa el singular para representar cada elemento individual.
La convención de plural para colecciones mejora la legibilidad significativamente. usuarios comunica que es un array de usuarios, mientras que usuario indica un solo elemento. En callbacks como map, filter y forEach, usar el singular (usuario, producto) para cada elemento hace que el código se lea de forma natural: "para cada usuario en usuarios" o "para cada producto en productos".
- <strong>Colecciones:</strong> Usa siempre nombres en plural (usuarios, productos, tareas)
- <strong>Elemento individual:</strong> Usa singular en callbacks (usuario, producto, tarea)
- <strong>Índices de bucles:</strong> Usa nombres descriptivos cuando sea posible (indiceUsuario vs i)
- <strong>Longitud de arrays:</strong> Prefija con total o cantidad (totalUsuarios, cantidadProductos)
Errores Comunes en Nombres
Hay varios errores comunes que los desarrolladores cometen al nombrar variables y funciones. Conocer estos patrones problemáticos te ayudará a evitarlos y escribir código más limpio y mantenible desde el principio.
Nombres de Una Sola Letra
Los nombres de una sola letra como i, j, x, y son aceptables solo en contextos muy específicos como índices de bucles o coordenadas matemáticas. En cualquier otro contexto, son completamente inútiles para entender el propósito del código.
El primer ejemplo usa nombres de una sola letra que no comunican nada sobre su propósito. El segundo ejemplo usa nombres descriptivos que explican exactamente qué representa cada variable. La diferencia en legibilidad es dramática, especialmente en código más complejo.
Números Mágicos
Los números mágicos son valores numéricos literales que aparecen en el código sin explicación de su propósito. Estos números deben extraerse a constantes con nombres descriptivos que expliquen qué representan y por qué tienen ese valor específico.
Los números 86400, 100 y 0.05 en el primer ejemplo son completamente opacos. El segundo ejemplo extrae estos valores a constantes con nombres explicativos: SEGUNDOS_POR_DIA, PORCENTAJE_MAXIMO y TASA_IMPUESTO. Ahora el código es autodocumentado y cualquier cambio futuro es más seguro.
Beneficio de extraer números mágicos
Extraer números mágicos a constantes con nombres descriptivos no solo mejora la legibilidad, sino que también facilita el mantenimiento. Si necesitas cambiar un valor, solo lo modificas en un lugar en lugar de buscar y reemplazar múltiples instancias del número en el código.
Resumen: Convenciones de Nombres
Conceptos principales:
- •camelCase para variables y funciones (ej: nombreUsuario, calcularTotal)
- •PascalCase para clases y constructores (ej: Usuario, Producto)
- •UPPER_SNAKE_CASE para constantes (ej: MAX_REINTENTOS, API_KEY)
- •Prefijos para booleanos: is, has, can, should, will
- •Plural para colecciones, singular para elementos (usuarios vs usuario)
- •handle para handlers, on para callbacks (handleClick vs onClick)
Mejores prácticas:
- •Usa nombres descriptivos que expliquen el propósito del código
- •Evita abreviaciones y nombres de una sola letra (excepto en bucles)
- •Extrae números mágicos a constantes con nombres significativos
- •Prefiere nombres específicos sobre genéricos (usuario vs data)
- •Usa # para campos privados reales, _ para privados por convención
- •El código se lee más que se escribe: invierte en buenos nombres