Guidelines for styling JavaScript code examples
The following guidelines cover how to write JavaScript example code for MDN Web Docs. This is a simple list for writing concise examples that will be understandable by as many people as possible. For guidelines that go into more detail, we'd recommend the AirBnB JavaScript Style Guide, which is generally compatible with our guidelines.
General guidelines for JavaScript code examples
Syntax style
-
We use expanded syntax for JavaScript - each line of JavaScript 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 promotes consistency on MDN Web Docs.
Follow this style for writing JavaScript code:
Don't use this style for writing JavaScript code:
function myFunc() { console.log('Hello!'); };
function myFunc() { console.log('Hello!'); };
- All statements must end with semicolons (";"). Although they're technically optional in JavaScript, we require them in all our code examples because we feel that they convey where each statement ends and make the code clearer.
- Use single quotes in JavaScript, wherever single quotes are needed in syntax.
Spacing
- There should be a space between a control statement and loop keywords and their opening parenthesis, as in
if () { ... }
andfor (...) { ... }
. - There should be a space between the opening parenthesis and the opening curly brace in such cases as described in the previous bullet.
- Include spaces between operators and operands, parameters, etc. For example, this is more readable with the spaces:
than this one without the spaces:
if (dayOfWeek === 7 && weather === 'sunny') { goOnTrip('beach', 'car', ['ice cream', 'bucket and spade', 'beach towel']); }
if (dayOfWeek===7&&weather==='sunny'){ goOnTrip('beach','car',['ice cream','bucket and spade','beach towel']); }
- Don't include padding spaces after and before opening and closing brackets. For example, use
(myVar)
, not( myVar )
.
JavaScript comments
Use JS-style comments to comment code that isn't self-documenting. Also note that you should leave a space between the slashes and the comment.
// This is a JavaScript-style comment
Put your comments on separate lines preceding the code they are referring to, like so:
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);
}
Modern JavaScript features
In MDN Web Docs code examples, you can use the modern and well-supported JavaScript features, such as arrow functions, promises, async
/await
, let
/const
, template literals, and spread syntax. We have used them in many places in these guidelines. We believe that the web industry has 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.
Arrays
Array creation
For creating arrays, use literals and not constructors.
Create arrays like this:
let myArray = [ ];
Don't do this while creating arrays:
let myArray = new Array(length);
Item addition
When adding items to an array, use push()
and not direct assignment. Given the following array:
const pets = [];
Add items to the array like this:
pets.push('cat');
Don't add items to the array like this:
pets[pets.length] = 'cat';
Conditionals
Loops
When loops are required, choose the appropriate one from for
, for...of
, while
, etc.
- There should be a space between a loop keyword and its opening parenthesis.
- There should be a space between the parentheses and the opening curly brace.
- When using the
for
orfor...of
loop, make sure to define the initializer properly with alet
keyword, as shown below:The example below does not follow the recommended guidelines for spacing or initialization.let cats = ['Athena', 'Luna']; for(let i of cats) { console.log(i); }
let cats = ['Athena', 'Luna']; for (i of cats) { console.log(i); }
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}`);
}
Control statements
- There should be a space between a control statement keyword and its opening parenthesis.
- There should be a space between the parentheses and the opening curly brace.
Write control statements with proper spacing like this:
if (iceCream) {
alert('Woo hoo!');
}
The example below does not follow the spacing guidelines:
if (iceCream){
alert('Woo hoo!');
}
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, as shown below:
try {
console.log(results);
}
catch(e) {
console.error(e);
}
Functions
Function names
For function names, use lowerCamelCasing. Use concise, human-readable, and semantic names where appropriate.
The following is a good example for a function name:
function sayHello() {
alert('Hello!');
};
Don't use function names like these:
function SayHello() {
alert('Hello!');
};
function notVeryObviousName() {
alert('Hello!');
};
Function declarations
- 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.
-
Where possible, use the
function
declaration to define functions over function expressions: This is the recommended way to declare a function:This is not a good way to define a function:function sum(a, b) { return a + b; }
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.
This is the recommended way:
Instead of this:
const array1 = [1, 2, 3, 4]; let sum = array1.reduce((a, b) => a + b );
const array1 = [1, 2, 3, 4]; let sum = array1.reduce(function(a, b) { return a + b; });
Objects
Object names
When defining an object class, 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, like so:
const hanSolo = new Person('Han Solo', 25, 'male');
const luke = {
name: 'Luke Skywalker',
age: 25,
gender: 'male'
};
Object creation
For creating general objects (i.e., when classes are not involved), use literals and not constructors.
For example, do this:
let myObject = { };
Don't create a general object like this:
let myObject = new Object();
Object classes
Use ES class syntax for objects, not old-style constructors.
For example, this is the recommended way:
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 {
// …
}
Operators
Conditional operators
Conditional (or ternary) operators should be put on a single line, as shown below:
let status = (age >= 18) ? 'adult' : 'minor';
Don't nest the conditional operators, as shown below, because the code is harder to read:
let status = (age >= 18)
? 'adult'
: 'minor';
Strict equality operator
Always use the "strict" equality and inequality operators over the equality and inequality operators.
Use the strict equality and inequality operators like this:
name === 'Chris';
age !== 25;
Don't use equality and inequality operators, as shown below:
name == 'Chris';
age != 25;
Shortcuts for boolean tests
Use shortcuts for boolean tests. For example, use x
and !x
, not x === true
and x === false
.
Strings
Template literals
For inserting values into strings, use template literals.
This is an example of the recommended way to use template literals:
let myName = 'Chris';
console.log(`Hi! I'm ${myName}!`);
Don;t concatenate strings like shown below:
let myName = 'Chris';
console.log('Hi! I\'m' + myName + '!');
Text content of a node
When inserting strings into DOM nodes, use Node.textContent
and not Element.innerHTML
. textContent
is a lot more efficient and less error-prone than innerHTML
.
The example below shows the use of textContent
.
let text = 'Hello to all you good people';
const para = document.createElement('p');
para.textContent = text;
Don't use innerHTML
to insert strings into DOM nodes.
let text = 'Hello to all you good people';
const para = document.createElement('p');
para.innerHTML = text;
Variables
Variable names
For variable names, use lowerCamelCasing. Use concise, human-readable, and semantic names where appropriate.
Use variable names like shown here:
let playerScore = 0;
let speed = distance / time;
Don't name variables like this:
let thisIsaveryLONGVariableThatRecordsPlayerscore345654 = 0;
let s = d/t;
Note: The only place where it's OK to not use human-readable, semantic names is where a very commonly recognized convention exists, such as using i
and j
for loop iterators.
Variable declarations
When declaring variables and constants, use the let
and const
keywords, not var
. The following examples show what's recommended and what's not on MDN Web Docs:
- If a variable will not be reassigned, prefer
const
, like so:const myName = 'Chris'; console.log(myName);
- If a variable will be reassigned, use
let
as shown below:let myAge = '40'; myAge++; console.log('Happy birthday!');
- The example below uses
let
where it should preferconst
. The code will work but this usage should be avoided in MDN Web Docs code examples.let myName = 'Chris'; console.log(myName);
- The example below uses
const
for a variable that gets reassigned. The reassignment will throw an error.const myAge = '40'; myAge++; console.log('Happy birthday!');
- The example below uses
var
, which should be avoided in code examples on MDN Web Docs.var myAge = '40'; var myName = 'Chris';
See also
- JavaScript language reference - browse through our JavaScript reference pages to check out some good, concise, meaningful CSS snippets. Our interactive examples in the "Try it" section are generally written to follow the guidelines described on this page.
- For API examples, you can check out the following:
fetch()
examplesfillRect()
examples- Payment Request API
show()
- Using the Web Audio API - this covers general good practices for HTML, CSS, and JavaScript and also provides a good demonstration of how to use snippets and add links to full examples elsewhere.
- Using the Media Capabilities API