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:
fetch()
examplesfillRect()
examples (the Canvas 2D examples are generally good, although they still use old-stylevar
).- Payment Request API
show()
(ThePaymentRequest
examples are generally quite good). - Using the Web Audio API (general good practices for HTML, CSS, and JavaScript, and a good demonstration of how to use snippets and link to full examples elsewhere).
- Using the Media Capabilities API (more general good practices for using code snippets in a guide).