Las siguientes pautas cubren la escritura de código de ejemplo JavaScript para los documentos web de MDN.Este artículo es una lista de reglas para escribir ejemplos concisos que sean comprensibles para la mayor cantidad de personas posible.

Pautas generales para ejemplos de código JavaScript

Esta sección explica las pautas generales a tener en cuenta al escribir ejemplos de código JavaScript.Las secciones posteriores cubrirán detalles más específicos.

Eligiendo un formato

Opiniones sobre la sangría correcta, espacio en blanco, y las longitudes de línea siempre han sido controvertidas.Las discusiones sobre estos temas son una distracción para la creación y mantenimiento de contenido.

En documentos web de MDN, usamosPrettier como formateador de código para mantener la consistencia del estilo del código (y para evitar discusiones fuera del tema).Puedes consultar nuestroArchivo de configuración para conocer las normas vigentes, y leer laDocumentación Prettier.

Prettier formatea todo el código y mantiene el estilo consistente. Sin embargo, hay algunas reglas adicionales que usted debe seguir.

Uso de características modernas de JavaScript

Usted puede usar nuevas funciones una vez que cada navegador principal — Chrome, Edge, Firefox, y Safari — las soporte.

Espaciado y sangría

Marque la sangría con2 espacios. No use el carácter de tabulación. El carácter de fin de línea es\n, la convención de Unix.Para ayudarle, hemos incluido un archivo.editorconfig en el repositorio.Muchos editores leen su contenido y lo utilizan para configurar su comportamiento.

Matrices

Creación de matrices

Para crear matrices, use literales y no constructores.

Crear matrices como esta:

const ciudadesVisitadas = [];

No hacer esto al crear matrices:

const ciudadesVisitadas = new Array(length);

Adición de elementos

Al agregar elementos a una matriz, usepush() y no asignación directa.Considere la siguiente matriz:

const mascotas = [];

Adicione elementos a la matriz de esta forma:

mascotas.push("gato");

No adicione elementos a la matriz de esta forma:

mascotas[mascotas.length] = "gato";

Métodos asíncronos

Escribir código asincrónico mejora el rendimiento y debe usarse cuando sea posible.En particular, puede utilizar:

• Promise
• async/await

Cuando ambas técnicas son posibles, preferimos usar la sintaxis más simpleasync/await.Desafortunadamente, no se puede utilizarawait en el nivel superior a menos que esté en un módulo ECMAScript.Los módulos CommonJS utilizados por Node.js no son módulos ES.Si su ejemplo está destinado a ser usado en todas partes, evite el nivel superiorawait.

Comentarios

Los comentarios son fundamentales para escribir buenos ejemplos de código.Aclaran la intención del código y ayudan a los desarrolladores a entenderlo.Préstale especial atención.

• Si el propósito o la lógica del código no es obvio, añade un comentario con tu intención, como se muestra debajo:

  js

  let total = 0;// Calcula la suma de los cuatro primeros elementos de arrfor (let i = 0; i < 4; i++) {  total += arr[i];}

  Por otro lado, reformular el código en prosa no es un buen uso de los comentarios:

  js

  let total = 0;// Bucle de 1 a 4for (let i = 0; i < 4; i++) {  // Adicionar valor al total  total += arr[i];}

• Los comentarios tampoco son necesarios cuando las funciones tienen nombres explícitos que describen lo que están haciendo. Escriba:

  js

  closeConnection();

  No escriba:

  js

  closeConnection(); // Cierra la conexión

Usar comentarios de una sola línea

Los comentarios de una sola línea se marcan con//, a diferencia de los comentarios en bloque encerrados entre/* … */.

En general, use comentarios de una sola línea para comentar el código.Los desarrolladores deben marcar cada línea del comentario con//, para que sea más fácil notar visualmente el código comentado.Además, esta convención permite comentar secciones de código utilizando/* … */ mientras se depura.

• Deje un espacio entre las barras y el comentario.Comienza con una letra mayúscula, como una oración, pero no termines el comentario con un punto.

  js

  // Este es un comentario de una sola línea bien escrito.

• Si un comentario no comienza inmediatamente después de un nuevo nivel de sangría, agregue una línea vacía y luego agregue el comentario.Creará un bloque de código, haciendo obvio a qué se refiere el comentario.Además, coloque sus comentarios en líneas separadas antes del código al que se refieren.Esto se muestra en el siguiente ejemplo:

  js

  function verificar(precioMercancias, precioEnvio, impuestos) {  // Calcula el precio total  const total = precioMercancias + precioEnvio + impuestos;  // Crea y agrega un nuevo párrafo al documento  const parrafo = document.createElement("p");  parrafo.textContent = `El precio total es ${total}`;  document.body.appendChild(parrafo);}

Salida de registros

• En el código destinado a ejecutarse en un entorno de producción, rara vez necesita comentar cuando registra algunos datos.En ejemplos de código, a menudo usamosconsole.log(),console.error(), o funciones similares para mostrar valores importantes.Para ayudar al lector a comprender lo que sucederá sin ejecutar el código, puede colocar un comentariodespués de la función con el registro que se producirá. Escriba:

  js

  function funcionEjemplo(canastaDeFrutas) {  console.log(canastaDeFrutas); // ['banana', 'mango', 'naranja']}

  No escriba:

  js

  function funcionEjemplo(canastaDeFrutas) {  // Registro: ['banana', 'mango', 'naranja']  console.log(canastaDeFrutas);}

• En caso de que la línea se vuelva demasiado larga, coloque el comentariodespués de la función, así:

  js

  function funcionEjemplo(canastaDeFrutas) {  console.log(canastaDeFrutas);  // ['banana', 'mango', 'naranja', 'manzana', 'pera', 'durian', 'limón']}

Comentarios de varias líneas

Los comentarios cortos suelen ser mejores, así que trate de mantenerlos en una línea de 60 a 80 caracteres.Si esto no es posible, utilice// al principio de cada línea:

// Este es un ejemplo de un comentario de varias líneas.// La función imaginaria que sigue, tiene algo inusual.// Limitaciones que quiero llamar.// Limitación 1// Limitación 2

No use/* … */:

/* Este es un ejemplo de un comentario de varias líneas.  La función imaginaria que sigue, tiene algo inusual.  Limitaciones que quiero llamar.  Limitación 1  Limitación 2 */

Usar comentarios para marcar puntos suspensivos

Omitir código redundante usando puntos suspensivos (…) es necesario para mantener los ejemplos cortos.Aun así, los escritores deben hacerlo cuidadosamente, ya que los desarrolladores con frecuencia copian y pegan ejemplos en su código, y todas nuestras muestras de código JavaScript deben ser válidas.

En JavaScript, debes poner los puntos suspensivos (…) en un comentario.Cuando sea posible, indique qué acción se espera que agregue quien reutilice este fragmento.

Usar un comentario para los puntos suspensivos (…) es mas explícito, previene errores cuando un desarrollador copia y pega un código de muestra.Escriba:

function funcionEjemplo() {  // Agrega tu código aquí  // …}

No uses puntos suspensivos (…) así:

function funcionEjemplo() {  …}

Comentar parámetros

Al escribir código, generalmente omite parámetros que no necesitas.Pero en algunos ejemplos de código, quieres demostrar que no utilizaste algunos posibles parámetros.

Para hacerlo, utilice/* … */ en la lista de parámetros.Esta es una excepción a la regla de usar solo comentarios de una sola línea. (//).

array.forEach((valor /* , índice, matriz */) => {  // …});

Funciones

Nombres de funciones

Para nombres de funciones, use camelCase, comenzando con un carácter en minúscula.Utilice nombres concisos, legibles por humanos y semánticos cuando sea apropiado.

El siguiente es un ejemplo correcto de un nombre de función:

function decirHola() {  console.log("Hola!");}

No use nombres de funciones como estos:

function DecirHola() {  console.log("Hola!");}function hazlo() {  console.log("Hola!");}

Declaración de funciones

• Siempre que sea posible, use la declaración de función sobre expresiones de función para definir funciones.

  Esta es la forma recomendada de declarar una función:

  js

  function suma(a, b) {  return a + b;}

  Esta no es una buena forma de declarar una función:

  js

  let suma = function (a, b) {  return a + b;};

• Al usar funciones anónimas como callback (una función pasada a otra invocación de método), si no necesitas acceder athis, use una función de flecha para hacer el código más corto y limpio.

  Esta es la forma recomendada:

  js

  const numeros = [1, 2, 3, 4];const suma = numeros.reduce((a, b) => a + b);

  En lugar de esto:

  js

  const numeros = [1, 2, 3, 4];const suma = numeros.reduce(function (a, b) {  return a + b;});

• Considere evitar usar la función de flecha para asignar una función a un identificador.En particular, no utilice funciones flecha para los métodos.Use declaración de funciones con la palabra clavefunction:

  js

  function x() {  // …}

  No lo hagas así:

  js

  const x = () => {  // …};

• Cuando utilice funciones flecha, utiliceretorno implícito (también conocido comocuerpo conciso) cuando sea posible:

  js

  matriz.map((e) => e.id);

  Y no:

  js

  matriz.map((e) => {  return e.id;});

Bucles y sentencias condicionales

Inicialización de bucle

Cuando losbucles son requeridos, elegir el apropiado entrefor(;;),for...of,while, etc.

• Al iterar a través de todos los elementos de la colección, evite usar el clásico buclefor (;;); es preferiblefor...of oforEach().Tenga en cuenta que si está utilizando una colección que no es unArray, tienes que comprobar quefor...of es realmente compatible (requiere que la variable sea iterable), o que el métodoforEach() está realmente presente.

  Usefor...of:

  js

  const perros = ["Rex", "Lassie"];for (const perro of perros) {  console.log(perro);}

  OforEach():

  js

  const perros = ["Rex", "Lassie"];perros.forEach((perro) => {  console.log(perro);});

  No usefor (;;) — no solo tienes que agregar un índice extra,i, sino que también tienes que rastrear la longitud de la matriz.Esto puede ser propenso a errores para principiantes.

  js

  const perros = ["Rex", "Lassie"];for (let i = 0; i < perros.length; i++) {  console.log(perros[i]);}

• Asegúrese de definir correctamente el inicializador utilizando la palabra claveconst parafor...of olet para los otros bucles.No lo omitas.Estos son ejemplos correctos:

  js

  const gatos = ["Athena", "Luna"];for (const gato of gatos) {  console.log(gato);}for (let i = 0; i < 4; i++) {  result += arr[i];}

  El siguiente ejemplo no sigue las pautas recomendadas para la inicialización (implícitamente crea una variable global y fallará en modo estricto):

  js

  const gatos = ["Athena", "Luna"];for (i of gatos) {  console.log(i);}

• Cuando necesite acceder tanto al valor como al índice, puede usar.forEach() en lugar defor (;;). Escriba:

  js

  const gerbils = ["Zoé", "Chloé"];gerbils.forEach((gerbil, i) => {  console.log(`Gerbil #${i}: ${gerbil}`);});

  No escriba:

  js

  const gerbils = ["Zoé", "Chloé"];for (let i = 0; i < gerbils.length; i++) {  console.log(`Gerbil #${i}: ${gerbils[i]}`);}

Sentencias de control

Hay un caso notable a tener en cuenta para las sentencias de controlif...else.Si la declaraciónif termina conreturn, no agregue una declaraciónelse.

Continúe justo después de la instrucciónif. Escriba:

if (prueba) {  // Realizar algo si la prueba es verdadera  // …  return;}// Realizar algo si la prueba es falsa// …

No escriba:

if (prueba) {  // Realizar algo si la prueba es verdadera  // …  return;} else {  // Realizar algo si la prueba es falsa  // …}

Use llaves con sentencias de flujo de control y bucles

Si bien las declaraciones de flujo de control comoif,for ywhile no requieren el uso de llaves cuando el contenido se compone de una sola declaración, siempre debe usar llaves.Escriba:

for (const carro of carrosAlmacenados) {  carro.pintar("rojo");}

No escriba:

for (const carro of carrosAlmacenados) carro.pintar("rojo");

Esto evita olvidarse de agregar las llaves al agregar más declaraciones.

Sentencias switch

Las sentenciasswitch pueden ser un poco complicadas.

• No agregue una declaraciónbreak después de una declaraciónreturn en un caso específico.En su lugar, escriba instruccionesreturn como esta:

  js

  switch (especies) {  case "pollo":    return farm.shed;  case "caballo":    return corral.entry;  default:    return "";}

  Si agrega una declaraciónbreak, será inalcanzable. No escriba:

  js

  switch (especies) {  case "pollo":    return farm.shed;    break;  case "caballo":    return corral.entry;    break;  default:    return "";}

• Usedefault como el último caso, y no lo termine con una declaraciónbreak.Si necesita hacerlo de otra manera, agregue un comentario explicando por qué.

• Recuerde que cuando declara una variable local para un caso, necesita usar llaves para definir un alcance:

  js

  switch (frutas) {  case "Naranja": {    const pedazo = frutas.cortar();    comer(pedazo);    break;  }  case "Manzana": {    const corazon = frutas.extraerCorazon();    reciclar(corazon);    break;  }}

Manejo de errores

• Si ciertos estados de su programa arrojan errores no detectados, detendrán la ejecución y reducirán potencialmente la utilidad del ejemplo.Por lo tanto, debe detectar errores utilizando un bloquetry...catch, Como se muestra debajo:

  js

  try {  console.log(obtenerResultado());} catch (e) {  console.error(e);}

• Cuando no necesite el parámetro de la sentenciacatch, omítalo:

  js

  try {  console.log(obtenerResultado());} catch {  console.error("Ocurrió un error!");}

Objetos

Nombre de objetos

• Al definir una clase, usePascalCase (comenzando con una letra mayúscula) para el nombre de la clase ycamelCase (comenzando con una letra minúscula) para la propiedad del objeto y los nombres de los métodos.

• Al definir una instancia de objeto, ya sea un literal o mediante un constructor, usecamelCase, comenzando con un carácter en minúsculas, para el nombre de la instancia. Por ejemplo:

  js

  const hanSolo = new Person("Han Solo", 25, "he/him");const luke = {  name: "Luke Skywalker",  age: 25,  pronouns: "he/him",};

Creación de objetos

Para crear objetos generales (es decir, cuando las clases no están involucradas), use literales y no constructores.

Por ejemplo, haz esto:

const objeto = {};

No crees un objeto general como este:

const objeto = new Object();

Clases de objetos

• Use la sintaxis de clase ES para objetos, no constructores de estilo antiguo.

  Por ejemplo, esta es la forma recomendada:

  js

  class Persona {  constructor(nombre, edad, pronombres) {    this.nombre = nombre;    this.edad = edad;    this.pronombres = pronombres;  }  greeting() {    console.log(`Hola! Yo soy ${this.nombre}`);  }}

• Usarextends para la herencia:

  js

  class Profesor extends Persona {  // …}

Métodos

Para definir métodos, utilice la sintaxis de definición de métodos:

const obj = {  foo() {    // …  },  bar() {    // …  },};

En lugar de:

const obj = {  foo: function () {    // …  },  bar: function () {    // …  },};

Propiedades del objeto

• El métodoObject.prototype.hasOwnProperty() ha quedado obsoleto en favor deObject.hasOwn().

• Cuando sea posible, use la abreviatura evitando la duplicación del identificador de la propiedad. Escriba:

  js

  function crearObjeto(nombre, edad) {  return { nombre, edad };}

  No escriba:

  js

  function crearObjeto(nombre, edad) {  return { nombre: nombre, edad: edad };}

Operadores

Esta sección enumera nuestras recomendaciones sobre qué operadores usar y cuándo.

Operadores condicionales

Cuando desee almacenar en una variable un valor literal dependiendo de una condición, use unoperador condicional (ternario) en lugar de una sentenciaif...else.Esta regla también se aplica cuando se devuelve un valor. Escriba:

const x = condicion ? 1 : 2;

No escriba:

let x;if (condicion) {  x = 1;} else {  x = 2;}

El operador condicional es útil al crear cadenas para registrar información.En tales casos, el uso de una instrucción regularif...else conduce a largos bloques de código para una operación secundaria como el registro, ofuscando el punto central del ejemplo.

Operador de igualdad estricta

Preferir los operadores deigualdad estricta=== y de desigualdad!== sobre los operadores de igualdad flexible== y de desigualdad!=.

Use los operadores estrictos de igualdad y desigualdad de esta forma:

nombre === "Shilpa";edad !== 25;

No use los operadores sueltos de igualdad y desigualdad, como se muestra a continuación:

nombre == "Shilpa";edad != 25;

Si necesita usar== o!=, recuerde que== null es el único caso aceptable.Como TypeScript fallará en todos los demás casos, no queremos tenerlos en nuestro código de ejemplo.Considere agregar un comentario para explicar por qué lo necesita.

Atajos para pruebas booleanas

Prefiera atajos para las pruebas booleanas. Por ejemplo, useif (x) yif (!x), no useif (x === true) yif (x === false), a menos que diferentes tipos de valores verdaderos o falsos se manejen de forma diferente.

Cadenas

Las cadenas literales se pueden encerrar entre comillas simples, como en'Una cadena', o entre comillas dobles, como en"Una cadena".No se preocupe por cuál usar, Prettier lo mantiene consistente.

Template literals

Para insertar valores en cadenas, usePlantillas literales.

• Aquí hay un ejemplo de la forma recomendada de usar plantillas literales.Su uso evita muchos errores de espaciado.

  js

  const nombre = "Shilpa";console.log(`¡Hola! Soy ${nombre}!`);

  No concatenes cadenas así:

  js

  const nombre = "Shilpa";console.log("¡Hola! Soy" + nombre + "!"); // ¡Hola! SoyShilpa!

• No abuses de las plantillas literales.Si no hay sustituciones, use una cadena literal normal en su lugar.

Variables

Nombre de Variables

Los buenos nombres de variables son esenciales para comprender el código.

• Use identificadores cortos y evite abreviaturas no comunes.Los buenos nombres de variables suelen tener entre 3 y 10 caracteres, pero solo como sugerencia.Por ejemplo, 'acelerómetro' es más descriptivo que abreviar como 'aclmtr' por el bien de la longitud de los caracteres.

• Trate de usar ejemplos relevantes del mundo real donde cada variable tenga una semántica clara.Solo recurra a nombres de marcadores de posición comofoo ybar cuando el ejemplo sea simple y artificial.

• No utilice la convención de nomenclaturaNotación húngara.No prefije el nombre de la variable con su tipo.Por ejemplo, escribabought = car.buyer !== null en lugar debBought = oCar.sBuyer != null oname = "John Doe" en lugar desName = "John Doe".

• Para colecciones, evite agregar el tipo como lista, matriz, cola en el nombre.Use el nombre del contenido en plural.Por ejemplo, para una matriz de autos, utilicecars y nocarArray ocarList.Puede haber excepciones, como cuando desea mostrar la forma abstracta de una función sin el contexto de una aplicación en particular.

• Para valores primitivos, usecamelCase, comenzando con un carácter en minúscula.No use_.Utilice nombres concisos, legibles por humanos y semánticos cuando sea apropiado.Por ejemplo, usecurrencyName en lugar decurrency_name.

• Evite el uso de artículos y posesivos.Por ejemplo, utilicecar en lugar demyCar oaCar.Puede haber excepciones, como cuando se describe una característica en general sin un contexto práctico.

• Use nombres de variables como se muestra aquí:

  js

  const playerScore = 0;const speed = distance / time;

  No nombre variables de esta forma:

  js

  const thisIsaveryLONGVariableThatRecordsPlayerscore345654 = 0;const s = d / t;

Declaración de Variables

Al declarar variables y constantes, use las palabras clavelet yconst, novar.Los siguientes ejemplos muestran lo que se recomienda y lo que no en los documentos web de MDN:

• Si una variable no se reasignará, prefieraconst, así:

  js

  const nombre = "Shilpa";console.log(nombre);

• Si va a cambiar el valor de una variable, uselet como se muestra a continuación:

  js

  let edad = 40;edad++;console.log("¡Feliz cumpleaños!");

• El siguiente ejemplo usalet donde debería serconst.El código funcionará, pero queremos evitar este uso en los ejemplos de código de los documentos web de MDN.

  js

  let nombre = "Shilpa";console.log(nombre);

• El siguiente ejemplo usaconst para una variable que se reasigna.La reasignación arrojará un error.

  js

  const edad = 40;edad++;console.log("¡Feliz cumpleaños!");

• El siguiente ejemplo usavar, contaminando el alcance global:

  js

  var edad = 40;var nombre = "Shilpa";

• Declare una variable por línea, así:

  js

  let var1;let var2;let var3 = "Apapou";let var4 = var3;

  No declare múltiples variables en una línea, separándolas con comas o usando declaraciones en cadena.Evite declarar variables así:

  js

  let var1, var2;let var3 = var4 = "Apapou"; // var4 se crea implícitamente como una variable global; falla en modo estricto

Coerción de tipos

Evite las coacciones de tipo implícito. En particular, evite+val para forzar un valor a un número y"" + val para forzarlo a una cadena.UtiliceNumber() yString(), sinnew, en su lugar. Escriba:

class Person {  #name;  #birthYear;  constructor(name, year) {    this.#name = String(name);    this.#birthYear = Number(year);  }}

No escriba:

class Person {  #name;  #birthYear;  constructor(name, year) {    this.#name = "" + name;    this.#birthYear = +year;  }}

APIs web para evitar

Además de estas características del lenguaje JavaScript, recomendamos tener en cuenta algunas pautas relacionadas con las API web.

Evite los prefijos del navegador

Si todos los principales navegadores (Chrome, Edge, Firefox y Safari) soportan una función, no agregue el prefijo de la función. Escriba:

const context = new AudioContext();

Evite la complejidad añadida de los prefijos. No escriba:

const AudioContext = window.AudioContext || window.webkitAudioContext;const context = new AudioContext();

La misma regla se aplica a los prefijos CSS.

Evite las API en desuso

Cuando un método, una propiedad o una interfaz completa está en desuso, no lo use (fuera de su documentación).En su lugar, utilice la API moderna.

Aquí hay una lista no exhaustiva de API web para evitar y con qué reemplazarlas:

• Usefetch() en lugar de XHR (XMLHttpRequest).
• UseAudioWorklet en lugar deScriptProcessorNode, en la API de Audio Web.

Use API seguras y confiables

• No utiliceElement.innerHTML para insertar contenido puramente textual en un elemento; useNode.textContent en su lugar.La propiedadinnerHTML genera problemas de seguridad si un desarrollador no controla el parámetro.Cuanto más evitamos usarlo como escritores, menos fallas de seguridad se crean cuando un desarrollador copia y pega nuestro código.

  El siguiente ejemplo demuestra el uso detextContent.

  js

  const text = "Hello to all you good people";const para = document.createElement("p");para.textContent = text;

  No useinnerHTML para insertartexto puro en los nodos DOM.

  js

  const text = "Hello to all you good people";const para = document.createElement("p");para.innerHTML = text;

• La funciónalert() no es fiable.No funciona en ejemplos en vivo en MDN Web Docs que están dentro de un<iframe>.Además, es modal para toda la ventana, lo cual es molesto.En ejemplos de código estático, useconsole.log() oconsole.error().Enejemplos en vivo, eviteconsole.log() yconsole.error() porque no se muestran.Utilice un elemento de interfaz de usuario dedicado.

Utilice el método de registro adecuado

• Al registrar un mensaje, utiliceconsole.log().
• Cuando registre un error, useconsole.error().

Vea también

Referencia del lenguaje JavaScript - navegue a través de nuestras páginas de referencia de JavaScript para ver algunos fragmentos de JavaScript buenos, concisos y significativos.