Indentation

Primitive Literals

Strings should always use double quotes (never single quotes) and should always appear on a single line. Never use a slash to create a new line in a string.

// Good
var name = "Nicholas";
// Bad: Single quotes
var name = 'Nicholas';
// Bad: Wrapping to second line
var longString = "Here's the story, of a man \
named Brady.";

Numbers should be written as decimal integers, e-notation integers, hexadecimal integers or floating-point decimals with at least one digit before and one digit after the decimal point. Never use octal literals.

Single-Line Comments

Single-line comments should be used to documentation one line of code or a group of related lines of code. A single-line comment may be used in three ways:

On a separate line, describing the code beneath it.

At the end of a line, describing the code before it.

On multiple lines, to comment out sections of code.

When on a separate line, a single-line comment should be at the same indentation level as the code it describes and be preceded by a single line. Never use multiple single-line comments on consecutive lines, use a multi-line comment instead.

// Good
if (condition){
// if you made it here, then all security checks passed
allowed();
}
// Bad: No empty line preceding comment
if (condition){
// if you made it here, then all security checks passed
allowed();
}
// Bad: Wrong indentation
if (condition){
// if you made it here, then all security checks passed
allowed();
}
// Bad: This should be a multi-line comment
// This next piece of code is quite difficult, so let me explain.
// What you want to do is determine if the condition is true
// and only then allow the user in. The condition is calculated
// from several different functions and may change during the
// lifetime of the session.
if (condition){
// if you made it here, then all security checks passed
allowed();
}

For single-line comments at the end of a line, ensure there is at least one indentation level between the end of the code and the beginning of the comment:

// Good
var result = something + somethingElse; // somethingElse will never be null
// Bad: Not enough space between code and comment
var result = something + somethingElse;// somethingElse will never be null

The only acceptable time to have multiple single-line comments on successive lines is to comment out large sections of code. Multi-line comments should not be used for this purpose.

Multi-Line Comments

Multi-line comments should be used to document code that requires more explanation. Each multi-line comment should have at least three lines:

The first line contains only the /* comment opening. No further text is allowed on this line.

The next line(s) have a * aligned with the * in the first line. Text is allowed on these lines.

The last line has the */ comment opening aligned with the preceding lines. No other text is allowed on this line.

The first line of multi-comments should be indented to the same level as the code it describes. Each subsequent line should have the same indentation plus one space (for proper alignment of the * characters). Each multi-line comment should be preceded by one empty line.

// Good
if (condition){
/*
* if you made it here,
* then all security checks passed
*/
allowed();
}
// Bad: No empty line preceding comment
if (condition){
/*
* if you made it here,
* then all security checks passed
*/
allowed();
}
// Bad: Missing a space after asterisk
if (condition){
/*
*if you made it here,
*then all security checks passed
*/
allowed();
}
// Bad: Wrong indentation
if (condition){
/*
* if you made it here,
* then all security checks passed
*/
allowed();
}
// Bad: Don't use multi-line comments for trailing comments
var result = something + somethingElse; /*somethingElse will never be null*/

Comment Annotations

Comments may be used to annotate pieces of code with additional information. These annotations take the form of a single word followed by a colon. The acceptable annotations are:

TODO - indicates that the code is not yet complete. Information about the next steps should be included.

HACK - indicates that the code is using a shortcut. Information about why the hack is being used should be included. This may also indicate that it would be nice to come up with a better way to solve the problem.

XXX - indicates that the code is problematic and should be fixed as soon as possible.

FIXME - indicates that the code is problematic and should be fixed soon. Less important than XXX.

REVIEW - indicates that the code needs to be reviewed for potential changes.

These annotations may be used with either single-line or multi-line comments and should follow the same formatting rules as the general comment type. Examples:

// Good
// TODO: I'd like to find a way to make this faster
doSomething();
// Good
/*
* HACK: Have to do this for IE. I plan on revisiting in
* the future when I have more time. This probably should
* get replaced before v1.2.
*/
if (document.all) {
doSomething();
}
// Good
// REVIEW: Is there a better way to do this?
if (document.all) {
doSomething();
}
// Bad: Annotation spacing is incorrect
// TODO : I'd like to find a way to make this faster
doSomething();
// Bad: Comment should be at the same indentation as code
// REVIEW: Is there a better way to do this?
if (document.all) {
doSomething();
}

Variable Declarations

All variables should be declared before they are used. Variable declarations should take place at the beginning of a function using a single var statement with one variable per line. All lines after the first should be indented one level so the variable names line up. Variables should be initialized when declared if applicable and the equals operator should be at a consistent indentation level. Initialized variables should come first followed by uninitialized variables.

Function Declarations

Functions should be declared before they are used. When a function is not a method (not attached to an object) it should be defined using function declaration format (not function expression format nor using the Function constructor). There should be no space between the function name and the opening parentheses. There should be one space between the closing parentheses and the right brace. The right brace should be on the same line as the function keyword. There should be no space after the opening parentheses or before the closing parentheses. Named arguments should have a space after the comma but not before it. The function body should be indented one level.

Naming

Care should be taken to name variables and functions properly. Names should be limited to alphanumeric characters and, in some cases, the underscore character. Do not use the dollar sign ($) or back slash (\) characters in any names.

Variable names should be formatted in camel case with the first letter being lowercase and the first letter of each subsequent word being uppercase. The first word of a variable name should be a noun (not a verb) to avoid confusion with functions. Do not use underscore for variable names.

Constructor functions, those functions used with the new operator to create new objects, should be formatted in camel case but must begin with an uppercase letter. Constructor function names should begin with a non-verb because new is the action of creating an object instance.

Object properties follow the same naming conventions as variables. Object methods follow the same naming conventions as functions. If a property or method is meant to be private, then it should be prefixed with an underscore character.

Compound Statements

Compound statements are lists of statements enclosed inside of braces.

The enclosed statements should be indented one more level than the compound statement.

The opening brace should be at the end of the line that begins the compound statement; the closing brace should begin a line and be indented to the beginning of the compound statement.

Braces are used around all statements, even single statements, when they are part of a control structure, such as a if or for statement. This makes it easier to add statements without accidentally introducing bugs due to forgetting to add braces.

The statement beginning keyword, such as if, should be followed by one space and the opening brace should be preceded by a space.

It is never permissible to omit the braces in any part of an if statement.

// Good
if (condition) {
doSomething();
}
// Bad: Improper spacing
if(condition){
doSomething();
}
// Bad: Missing braces
if (condition)
doSomething();
// Bad: All on one line
if (condition) { doSomething(); }
// Bad: All on one line without braces
if (condition) doSomething();

try Statement

White Space

Blank lines improve readability by setting off sections of code that are logically related.

Two blank lines should always be used in the following circumstances:

Between sections of a source file

Between class and interface definitions

One blank line should always be used in the following circumstances:

Between methods

Between the local variables in a method and its first statement

Before a multi-line or single-line comment

Between logical sections inside a method to improve readability

Blank spaces should be used in the following circumstances:

A keyword followed by a parenthesis should be separated by a space.

A blank space should appear after commas in argument lists.

All binary operators except dot (.) should be separated from their operands by spaces. Blank spaces should never separate unary operators such as unary minus, increment (++), and decrement (--) from their operands.

The expressions in a for statement should be separated by blank spaces. Blank spaces should only be used after semicolons, not before.

Things to Avoid

Never use the primitive wrapper types, such as String, to create new objects.

Never use eval().

Never use the with statement. This statement isn’t available in strict mode and likely won’t be available in future ECMAScript editions.