Javascript-coding-guidelines.md

@@ -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