Coding style guide

/!\ WORK IN PROGRESS -- DO NOT EDIT /!\

Table of contents

• JavaScript Filenames
• Line length
• Strictness
• Indentation
• Comments
• Variable declarations
• Block statements
• if statements
• return statements
• Function declarations
• Names
• Semicolons
• Blank lines and whitespaces
• Strings
• Dependencies

JavaScript Filenames

• Filenames must be lowercase.
• Words are separated by a dash -

Examples

# Good
my-file.js

Line length

• Avoid lines longer than 80 characters.
• Exception can be made for long strings or comments.
• When breaking a line, place the break after an operator, not before.

Examples

// Good
foo() +
bar();

// Bad
foo()
+ bar();

Rationale

• Short lines are more readable that long lines.
• This also allows for screen splitting edition without scrolling horizontally.
• A break after an operator decreases the likelihood that a copy-paste error will be masked by semicolon insertion.

Strictness

• Always use the strict mode.
• Always start a file with 'use strict'; on the very first line unless there is block comment at line 1. In that case, leave a blank between the block comment and the strict mode statement.

Rationale

• Strict mode helps detecting numerous bugs, such as a leaked variable.

Indentation

• The unit of indentation is 2 spaces.
• Use spaces instead of tabs.

Rationale

• This leaves more room for the 80-char max length.
• The performance overhead of the 2 spaces is not relevant.

Comments

• Use inline comments for meaningful explanations.
• Use block comments for formal documentation (and only for that)

Variable declarations

• Use of global variables should be avoided.
• All variables must be declared before used.
• The variable declarations should be the first statement in the function body.
• Declare one variable per line, in alphabetical order if possible.
• Start each statement with var.

Examples

// Good
var bar = 'foo';
var foo = 'bar';

// Bad
var bar = 'foo'
,   foo = 'bar'
;

// Bad
var bar = 'foo',
    foo = 'bar';

Rationale

• Declaring variables helps to detect undeclared variables that may become implied globals.
• A missing comma, due to semicolon insertion, will make the variable global instead of local, which is most likely a mistake.
• Being explicit about var is the best way to avoid mistakes and to keep git from messing up the diff when a variable is changed or added.

Block statements

• Opening braces go on the same line as the statement.
• Insert one space before the opening curly brace.

// Good
if (condition) {
  /* ... */
}

// Good
function () {
  /* ... */
}

// Bad
if (true)
{
  console.log('losing');
}

// Bad
function ()
{
  /* ... */
}

// Bad
if(foo){
  /* ... */
}

if statements

• In the presence of a single statement:
  • If the condition and the statement are shorter than 80 character, have them on the same line
  • Otherwise, break it and make us of curly brackets
• Always use curly brackets when the if body is made of multiple statements
• if and the conditions must be separated by one space.
• Use === and !== operators instead of == and !=.

Examples

// Good
if (foo) {
  bar1();
  bar2();
}

// Good
if (foo1) bar1();
else if (foo2) bar2();
else notBar();

// Bad
if (foo1) {
  bar1();
}
else if (foo2) {
  bar2();
}
else {
  notBar();
}

Rationale

• Short lines are preferred for readability.
• Being able to compact an if statement helps having the entire outer block readable with no scroll.
• == and != operators do type coercion and should not be used.

return statements

• return statements should always be the last statement of a function.

Rationale

• This helps understanding the flow of a complex function and helps debugging.

Function declarations

• All functions should be declared before they are used.
• Inner functions should follow the var statements.
• Do not insert spaces between the function name and the arguments.
• If a function literal is anonymous, insert one space before the word function and the arguments.
• Keep your functions short, about 15 lines maximum per function.
• Closures should be named, as it produces better stack traces.
• Short closures with a single statement can be one-liners as long as the max line length is respected.

Examples

// Good
function foo(bar) {
  // ...
}
var foo = function foo (bar) { return bar; };

// Sort of good
function (bar) {
  // ...
}

// Bad
function foo (bar) {
  // ...
}
function(bar) {
  // ...
}

Names

• Do not use international characters, $ or \ in names.
• Do not use _ as the first of last character of a name.
• Use lowerCamelCase for function and variable names.
• Use UpperCamelCase for class names.
• Use UPPERCASE for pseudo-constants.
• Node.js supports the keyword const for global contants.

// Good
var myVar;
var MyClass;
var myFunction;

// Bad
var $;
var _iAmSoPublic;

Rationale

• JavaScript issues neither a compile-time warning nor a run-time warning if a required new is omitted. The capitalization convention is the only defense we have.

Semicolons

• Put a semicolon at the end of every statement.

Rationale

• JavaScript allows any expression to be used as a statement. This can mask some errors, particularly in the presence of semicolon insertion. Therefore lines without semicolons at the end must be read as a typo.

Blank lines and whitespaces

• Be reasonable with blank lines.
  • No blank lines before closing curly brackets.
  • No blank lines after a function declaration.
• Add a blank line only to split big statement blocks, when it is necessary.
• Leave an empty line at the end of each file.
• Do not commit trailing whitespaces.

Rationale

• The shorter the better, as it helps reading more without scrolling back and forth.
• Git will complain if an empty line at the end of file is missing.

Strings

• Use single quotes rather than double quotes.

npm dependencies

• Keep dependencies and devDependencies sorted alphabetically.
• Versioning:
  • If major version M > 0, use the following: M.x.x
  • Otherwise, keep the minor version m fixed: 0.m.x

Rationale

• The sorted dependency list will match David's list, easier to update the dependencies.
• According to man semver, "Many authors treat a 0.x version as if the x were the major 'breaking-change' indicator".

/!\ WORK IN PROGRESS -- DO NOT EDIT /!\