JavaScript guidelines

The following guidelines cover how to write JavaScript for MDN code examples.

The following is a fairly simple set of JavaScript guidelines. We could go a lot deeper on this, but essentially we want to provide simple guidelines for writing concise examples that will be understandable by as many people as possible, rather than detailed guidelines for writing complex web apps. If you want something that goes into more detail, we'd recommend the AirBnB JavaScript Style Guide, which is generally compatible with our guidelines.

In this article

General JavaScript guidelines

Use expanded syntax

For JavaScript we use expanded syntax, with each line of JS on a new line, the opening brace of a block on the same line as its associated statement, and the closing brace on a new line. This maximizes readability, and again, promotes consistency on MDN.

Do this

function myFunc() {
  console.log('Hello!');
};

Not this

function myFunc() { console.log('Hello!'); };

We also have a few specific rules around spacing inside language features. You should include spaces between operators and operands, parameters, etc.

This is more readable

if(dayOfWeek === 7 && weather === 'sunny') {
  goOnTrip('beach', 'car', ['ice cream', 'bucket and spade', 'beach towel']);
}

than this

if(dayOfWeek===7&&weather==='sunny'){
  goOnTrip('beach','car',['ice cream','bucket and spade','beach towel']);
}

In addition, keep these specifics in mind:

  • Don't include padding spaces after opening brackets or before closing brackets — (myVar), not ( myVar ).
  • All statements must end with semicolons (";"). We require them in all of our code samples even though they're technically optional in JavaScript because we feel that it leads to code that is clearer and more precise about where each statement ends.
  • Use single quotes in JavaScript, wherever single quotes are needed in syntax.
  • There should be no space between a control statement keyword, function, or loop keyword and its opening parenthesis (e.g. if() { ... }, function myFunc() { ... }, for(...) { ... }).
  • There should be a space between the parentheses and the opening curly brace in such cases as described in the previous bullet.

JavaScript comments

Use JS-style comments to comment code that isn't self-documenting:

// This is a JavaScript-style comment

Put your comments on separate lines preceding the code they are referring to:

function myFunc() {
  // Output the string 'Hello' to the browser's JS console
  console.log('Hello');
  // Create a new paragraph, fill it with content, and append it to the <body>
  let para = document.createElement('p');
  para.textContent = 'My new paragraph';
  document.body.appendChild(para);
}

Also note that you should leave a space between the slashes and the comment, in each case.

Use modern JS features

For general usage, you can use modern well-supported JS features (such as arrow functions, promises, async/await, let/const, template literals, and spread syntax) in MDN examples. We include them in many places in these guidelines, as we believe the web industry has generally gotten to the point where such features are familiar enough to be understandable. And for those that don't use them yet, we'd like to play our part in helping people to evolve their skills.

Note: By "general usage", we mean general example writing. Reference pages covering specific JS features obviously need to use the features they are documenting!

Variables

Variable naming

For variable names use lowerCamelCasing, and use concise, human-readable, semantic names where appropriate.

Do this:

let playerScore = 0;

let speed = distance / time;

Not this:

let thisIsaveryLONGVariableThatRecordsPlayerscore345654 = 0;

let s = d/t;

Note: The only place where it is OK to not use human-readable semantic names is where a very common recognized convention exists, such as using i, j, etc. for loop iterators.

Declaring variables

When declaring variables and constants, use the let and const keywords, not var.

If a variable will not be reassigned, prefer const:

const myName = 'Chris';
console.log(myName);

Otherwise, use let:

let myAge = '40';
myAge++;
console.log('Happy birthday!');

This example uses let where it should prefer const. It will work but should be avoided in MDN code examples:

let myName = 'Chris';
console.log(myName);

This example uses const for a variable that gets reassigned. The reassignment will throw an error:

const myAge = '40';
myAge++;
console.log('Happy birthday!');

This example uses var, which should be avoided in MDN code examples unless it is really needed:

var myAge = '40';
var myName = 'Chris';

Operators and comparison

Ternary operators

Ternary operators should be put on a single line:

let status = (age >= 18) ? 'adult' : 'minor';

Not nested:

let status = (age >= 18)
  ? 'adult'
  : 'minor';

This is much harder to read.

Use strict equality

Always use strict equality and inequality.

Do this:

name === 'Chris';
age !== 25;

Not this:

name == 'Chris';
age != 25;

Use shortcuts for boolean tests

Use shortcuts for boolean tests — use x and !x, not x === true and x === false.

Control statements

Write control statements like this:

if(iceCream) {
  alert('Woo hoo!');
}

Not this:

if (iceCream){
  alert('Woo hoo!');
}

Also bear in mind:

  • There should be no space between a control statement keyword and its opening parenthesis.
  • There should be a space between the parentheses and the opening curly brace.

Strings

Use template literals

For inserting values into strings, use string literals.

Do this:

let myName = 'Chris';
console.log(`Hi! I'm ${myName}!`);

Not this:

let myName = 'Chris';
console.log('Hi! I\'m' + myName + '!');

Use textContent, not innerHTML

When inserting strings into DOM nodes, use Node.textContent:

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

Not Element.innerHTML:

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

textContent is a lot more efficient, and less error-prone than innerHTML.

Conditionals

General purpose looping

When loops are required, feel free to choose an appropriate loop out of the available ones (for, for...of, while, etc.) Just make sure to keep the code as understandable as possible.

When using for/for...of loops, make sure to define the initializer properly, with a let keyword:

let cats = ['Athena', 'Luna'];
for(let i of cats) {
  console.log(i);
}

Not

let cats = ['Athena', 'Luna'];
for(i of cats) {
  console.log(i);
}

Also bear in mind:

  • There should be no space between a loop keyword and its opening parenthesis.
  • There should be a space between the parentheses and the opening curly brace.

Switch statements

Format switch statements like this:

let expr = 'Papayas';
switch(expr) {
  case 'Oranges':
    console.log('Oranges are $0.59 a pound.');
    break;
  case 'Papayas':
    console.log('Mangoes and papayas are $2.79 a pound.');
    // expected output: "Mangoes and papayas are $2.79 a pound."
    break;
  default:
    console.log(`Sorry, we are out of ${expr}`);
}

Functions and objects

Function naming

For function names use lowerCamelCasing, and use concise, human-readable, semantic names where appropriate.

Do this:

function sayHello() {
  alert('Hello!');
};

Not these:

function SayHello() {
  alert('Hello!');
};

function notVeryObviousName() {
  alert('Hello!');
};

Defining functions

Where possible, use the function declaration to define functions over function expressions:

Do this:

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

Not this:

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

When using anonymous functions inside a method that requires a function as a parameter, it is acceptable (although not required) to use an arrow function to make the code shorter and cleaner.

So instead of this:

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

you could write this:

const array1 = [1, 2, 3, 4];
let sum = array1.reduce((a, b) =>
  a + b
);

Also bear in mind:

  • There should be no space between a function name and its opening parenthesis.
  • There should be a space between the parentheses and the opening curly brace.

Creating objects

Use literals — not constructors — for creating general objects (i.e., when classes are not involved):

Do this:

let myObject = { };

Not this:

let myObject = new Object();

Object classes

Use ES class syntax for objects, not old-style constructors.

For example:

class Person {
  constructor(name, age, gender) {
    this.name = name;
    this.age = age;
    this.gender = gender;
  }

  greeting() {
    console.log(`Hi! I'm ${this.name}`);
  };
}

Use extends for inheritance:

class Teacher extends Person {
  ...
}

Object naming

When defining an object class (as seen above), use UpperCamelCasing (also known as PascalCasing) for the class name, and lowerCamelCasing for the object property and method names.

When defining an object instance, either a literal or via a constructor, use lowerCamelCase for the instance name:

let hanSolo = new Person('Han Solo', 25, 'male');

let hanSolo = {
  name: 'Han Solo',
  age: 25,
  gender: 'male'
}

Arrays

Creating arrays

Use literals — not constructors — for creating arrays:

Do this:

let myArray = [ ];

Not this:

let myArray = new Array(length);

Adding to an array

When adding items to an array, use push(), not direct assignment. Given the following array:

const pets = [];

do this:

pets.push('cat');

not this:

pets[pets.length] = 'cat';

Error handling

If certain states of your program throw uncaught errors, they will halt execution and potentially reduce the usefulness of the example. You should therefore catch errors using a try...catch block:

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

Good JavaScript examples on MDN

You can find good, concise, meaningful JavaScript snippets at the top of our JavaScript language reference pages — browse through it to find some.

Our interactive (and other) examples are generally written to follow the above guidelines, although be aware that they may differ in some places as they were mostly written before the guidelines were newly written.

For API examples, we'd like to highlight a few examples we think are good: