Coding style guide

[WORK IN PROGRESS -- DO NOT EDIT]

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 limit.
• 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 foo = 'bar';
var bar = 'foo';

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

Rationale

• Declaring variables helps to detect undeclared variables that may become implied globals.

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.
• Insert one space between the arguments and the opening curly brace.
• 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.

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.

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.

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.
• The condition and the opening curly bracket 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();
}

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

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.

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.

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".

Git commit messages

• Use imperative present tense for commit messages as suggested in the official documentation.
• When commiting a fix, start your line with "Fix #xx", xx being the issue number.

Examples

Good:
git commit -m 'Fix #42: Answer the Ultimate Question of Life, The Universe, and Everything'

[WORK IN PROGRESS -- DO NOT EDIT]