Changes

Page history
Update Javascript coding guidelines authored by Moreau Nicolas's avatar Moreau Nicolas
Hide whitespace changes
Inline Side-by-side
Javascript-coding-guidelines.md
View page @ 02d484ff
......@@ -28,12 +28,11 @@ You should include spaces between operators and operands, parameters, etc...
Example :
`if(dayOfWeek === 7 && weather === 'sunny') {`
`goOnTrip('beach', 'car', ['ice cream', 'bucket and spade', 'beach towel']);`
`}`
```javascript
if(dayOfWeek === 7 && weather === 'sunny') {
goOnTrip('beach', 'car', ['ice cream', 'bucket and spade', 'beach towel']);
}
```
Other rules :
```plaintext
......@@ -56,21 +55,16 @@ Use JS-style comments to comment code that isn't self-documenting:
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`
`let para = document.createElement('p');`
`para.textContent = 'My new paragraph';`
`document.body.appendChild(para);`
`}`
```javascript
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
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.
......@@ -81,16 +75,17 @@ Also note that you should leave a space between the slashes and the comment, in
For variable names use lowerCamelCasing, and use concise, human-readable, semantic names where appropriate.
Do this:
`let playerScore = 0;`
`let speed = distance / time;`
```javascript
let playerScore = 0;
let speed = distance / time;
```
not this :
`let thisIsaveryLONGVariableThatRecordsPlayerscore345654 = 0;`
`let s = d/t;`
```javascript
let thisIsaveryLONGVariableThatRecordsPlayerscore345654 = 0;
let s = d/t;
```
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.
......@@ -100,17 +95,18 @@ 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);`
```javascript
const myName = 'Chris';
console.log(myName);
```
Otherwise, use let:
`let myAge = '40';`
`myAge++;`
`console.log('Happy birthday!');`
```javascript
let myAge = '40';
myAge++;
console.log('Happy birthday!');
```
##
......@@ -120,15 +116,17 @@ Otherwise, use let:
Ternary operators should be put on a single line:
`let status = (age >= 18) ? 'adult' : 'minor';`
```javascript
let status = (age >= 18) ? 'adult' : 'minor';
```
Not nested:
`let status = (age >= 18)`
`? 'adult'`
`: 'minor';`
```javascript
let status = (age >= 18)
? 'adult'
: 'minor';
```
### Use strict equality
......@@ -136,15 +134,17 @@ Always use strict equality and inequality.
Do this:
`name === 'Chris';`
`age !== 25;`
```javascript
name === 'Chris';
age !== 25;
```
Not this:
`name == 'Chris';`
`age != 25;`
```javascript
name == 'Chris';
age != 25;
```
### Use shortcuts for boolean tests
......@@ -158,11 +158,11 @@ Use shortcuts for boolean tests — use x and !x, not x === true and x === false
- There should be a space between the parentheses and the opening curly brace.
```
`if(iceCream) {`
`alert('Woo hoo!');`
`}`
```javascript
if(iceCream) {
alert('Woo hoo!');
}
```
## Strings
......@@ -172,32 +172,35 @@ For inserting values into strings, use string literals.
Do this:
`let myName = 'Chris';`
`` console.log(`Hi! I'm ${myName}!`); ``
```javascript
let myName = 'Chris';
console.log(`Hi! I'm ${myName}!`);
```
Not this :
`let myName = 'Chris';`
`console.log('Hi! I\'m' + myName + '!');`
```javascript
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;`
```javascript
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');`
```javascript
let text = 'Hello to all you good people';
const para = document.createElement('p');
```
textContent is a lot more efficient, and less error-prone than innerHTML.
......@@ -209,51 +212,40 @@ When loops are required, choose an appropriate loop out of the available ones (f
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);`
`}`
```javascript
let cats = ['Athena', 'Luna'];
for(let i of cats) {
console.log(i);
}
```
Not :
`let cats = ['Athena', 'Luna'];`
`for(i of cats) {`
`console.log(i);`
`}`
```javascript
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}`); ``
`}`
```javascript
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
......@@ -263,11 +255,11 @@ For function names use lowerCamelCasing, and use concise, human-readable, semant
Do this:
`function sayHello() {`
`alert('Hello!');`
`};`
```javascript
function sayHello() {
alert('Hello!');
};
```
### Defining functions
......@@ -275,29 +267,27 @@ Where possible, use the function declaration to define functions over function e
Do this:
`function sum(a, b) {`
`return a + b;`
`}`
```javascript
function sum(a, b) {
return a + b;
}
Not this :
`let sum = function(a, b) {`
`return a + b;`
`}`
```javascript
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.
`const array1 = [1, 2, 3, 4];`
`let sum = array1.reduce((a, b) =>`
`a + b`
`);`
```javascript
const array1 = [1, 2, 3, 4];
let sum = array1.reduce((a, b) =>
a + b
);
```
### Creating objects
......@@ -305,11 +295,15 @@ Use literals — not constructors — for creating general objects (i.e., when c
Do this:
`let myObject = { };`
```javascript
let myObject = { };
```
Not this :
`let myObject = new Object();`
```javascript
let myObject = new Object();
```
### Object classes
......@@ -317,33 +311,27 @@ 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}`); ``
` };`
`}`
```javascript
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 {`
`...`
`}`
```javascript
class Teacher extends Person {
...
}
```
### Object naming
......@@ -351,17 +339,14 @@ When defining an object class (as seen above), use UpperCamelCasing (also known
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'`
`}`
```javascript
let hanSolo = new Person('Han Solo', 25, 'male');
let hanSolo = {
name: 'Han Solo',
age: 25,
gender: 'male'
}
```
## Arrays
......@@ -371,41 +356,49 @@ Use literals — not constructors — for creating arrays:
Do this:
`let myArray = [ ];`
```javascript
let myArray = [ ];
```
Not this :
`let myArray = new Array(length);`
```javascript
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 = [];`
```javascript
const pets = [];
```
Do this :
`pets.push('cat');`
```javascript
pets.push('cat');
```
not this :
`pets[pets.length] = 'cat';`
```javascript
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);`
```javascript
try {
console.log(results);
}
`}`
catch(e) {
console.error(e);
}
````
## Documenting code
......@@ -419,7 +412,7 @@ JSDoc comments should generally be placed immediately before the code being docu
### Documenting a function
```
```javascript
/**
* Returns the sum of a and b
* @param {number} a
......@@ -433,7 +426,7 @@ function sum(a, b) {
### Documenting a class
```
```javascript
/**
* Class representing a dot.
* @extends Point
......
......