Table of Contents for

Maintainable JavaScript

Each indentation level is made up of four spaces. Do not use tabs.

// Good
if (true) {
    doSomething();
}

Each line should be no longer than 80 characters. If a line goes longer than 80 characters, it should be wrapped after an operator (comma, plus, etc.). The following line should be indented two levels (eight characters).

// Good
doSomething(argument1, argument2, argument3, argument4,
        argument5);

// Bad: Following line only indented four spaces
doSomething(argument1, argument2, argument3, argument4,
    argument5);

// Bad: Breaking before operator
doSomething(argument1, argument2, argument3, argument4
        , argument5);

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.

// Good
var count = 10;

// Good
var price = 10.0;
var price = 10.00;

// Good
var num = 0xA2;

// Good
var num = 1e23;

// Bad: Hanging decimal point
var price = 10.;

// Bad: Leading decimal point
var price = .1;

// Bad: Octal (base 8) is deprecated
var num = 010;

The special value null should be used only in the following situations:

Examples:

// Good
var person = null;

// Good
function getPerson() {
    if (condition) {
        return new Person("Nicholas");
    } else {
        return null;
    }
}

// Good
var person = getPerson();
if (person !== null){
    doSomething();
}

// Bad: Testing against uninitialized variable
var person;
if (person != null){
    doSomething();
}

// Bad: Testing to see if an argument was passed
function doSomething(arg1, arg2, arg3, arg4){
    if (arg4 != null){
        doSomethingElse();
    }
}

Never use the special value undefined. To see if a variable has been defined, use the typeof operator:

// Good
if (typeof variable == "undefined") {
    // do something
}

// Bad: Using undefined literal
if (variable == undefined) {
    // do something
}

Operators with two operands must be preceded and followed by a single space to make the expression clear. Operators include assignments and logical operators.

// Good
var found = (values[i] === item);

// Good
if (found && (count > 10)) {
    doSomething();
}

// Good
for (i = 0; i < count; i++) {
    process(i);
}

// Bad: Missing spaces
var found = (values[i]===item);

// Bad: Missing spaces
if (found&&(count>10)) {
    doSomething();
}

// Bad: Missing spaces
for (i=0; i<count; i++) {
    process(i);
}

When parentheses are used, there should be no white space immediately after the opening paren or immediately before the closing paren.

// Good
var found = (values[i] === item);

// Good
if (found && (count > 10)) {
    doSomething();
}

// Good
for (i = 0; i < count; i++) {
    process(i);
}

// Bad: Extra space after opening paren
var found = ( values[i] === item);

// Bad: Extra space before closing paren
if (found && (count > 10) ) {
    doSomething();
}

// Bad: Extra space around argument
for (i = 0; i < count; i++) {
    process( i );
}

Object literals should have the following format:

Examples:

// Good
var object = {

    key1: value1,
    key2: value2,

    func: function() {
        // do something
    },

    key3: value3
};

// Bad: Improper indentation
var object = {
                key1: value1,
                key2: value2
            };

// Bad: Missing blank lines around function
var object = {

    key1: value1,
    key2: value2,        
    func: function() {
        // do something
    },        
    key3: value3
};

When an object literal is passed to a function, the opening brace should be on the same line as if the value is a variable. All other formatting rules listed earlier still apply.

// Good
doSomething({
    key1: value1,
    key2: value2
});

// Bad: All on one line
doSomething({ key1: value1, key2: value2 });

Make frequent use of comments to aid others in understanding your code. Use comments when:

// 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 multiline 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();
}

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

// Good
// if (condition){
//    doSomething();
//    thenDoSomethingElse();
// }

// 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*/

// 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();
}

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

// Good
var count   = 10,
    name    = "Nicholas",
    found   = false,
    empty;

// Bad: Improper initialization alignment
var count = 10,
    name = "Nicholas",
    found= false,
    empty;

// Bad: Incorrect indentation
var count   = 10,
name    = "Nicholas",
found   = false,
empty;

// Bad: Multiple declarations on one line
var count   = 10, name = "Nicholas",
    found   = false, empty;

// Bad: Uninitialized variables first
var empty,
    count   = 10,
    name    = "Nicholas",
    found   = false;

// Bad: Multiple var statements
var count   = 10,
    name    = "Nicholas";

var found   = false,
    empty;

Always declare variables. Implied globals should not be used.

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

// Good
function doSomething(arg1, arg2) {
    return arg1 + arg2;
}

// Bad: Improper spacing of first line
function doSomething (arg1, arg2){
    return arg1 + arg2;
}

// Bad: Function expression
var doSomething = function(arg1, arg2) {
    return arg1 + arg2;
};

// Bad: Left brace on wrong line
function doSomething(arg1, arg2)
{
    return arg1 + arg2;
}

// Bad: Using Function constructor
var doSomething = new Function("arg1", "arg2", "return arg1 + arg2");

Functions declared inside of other functions should be declared immediately after the var statement.

// Good
function outer() {

    var count   = 10,
        name    = "Nicholas",
        found   = false,
        empty;

    function inner() {
        // code
    }

    // code that uses inner()
}

// Bad: Inner function declared before variables
function outer() {

    function inner() {
        // code
    }        

    var count   = 10,
        name    = "Nicholas",
        found   = false,
        empty;

    // code that uses inner()
}

Anonymous functions may be used for assignment of object methods or as arguments to other functions. There should be no space between the function keyword and the opening parenthesis.

// Good
object.method = function() {
    // code
};

// Bad: Incorrect spacing
object.method = function () {
    // code
};

Immediately invoked functions should surround the entire function call with parentheses.

// Good
var value = (function() {

    // function body

    return {
        message: "Hi"
    }
}());

// Bad: No parentheses around function call
var value = function() {

    // function body

    return {
        message: "Hi"
    }
}();

// Bad: Improper parentheses placement
var value = (function() {

    // function body

    return {
        message: "Hi"
    }
})();

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 backslash (\) characters in any names.

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

// Good
var accountNumber = "8401-1";

// Bad: Begins with uppercase letter
var AccountNumber = "8401-1";

// Bad: Begins with verb
var getAccountNumber = "8401-1";

// Bad: Uses underscore
var account_number = "8401-1";

Function names should also be formatted using camel case. The first word of a function name should be a verb (not a noun) to avoid confusion with variables. Do not use underscores in function names.

// Good
function doSomething() {
    // code        
}

// Bad: Begins with uppercase letter
function DoSomething() {
    // code
}

// Bad: Begins with noun
function car() {
    // code
}

// Bad: Uses underscores
function do_something() {
    // code
}

Constructor functions—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 nonverb, because new is the action of creating an object instance.

// Good
function MyObject() {
    // code
}

// Bad: Begins with lowercase letter
function myObject() {
    // code
}

// Bad: Uses underscores
function My_Object() {
    // code
}

// Bad: Begins with verb
function getMyObject() {
    // code
}

Variables that act as constants (values that won’t be changed) should be formatted using all uppercase letters with words separated by a single underscore.

// Good
var TOTAL_COUNT = 10;

// Bad: Camel case
var totalCount = 10;

// Bad: Mixed case
var total_COUNT = 10;

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.

// Good
var object = {    
    _count: 10,

    _getCount: function () {
        return this._count;
    }
};

Strict mode should be used only inside of functions, never globally.

// Bad: Global strict mode
"use strict";

function doSomething() {
    // code
}

// Good
function doSomething() {
    "use strict";

    // code
}

If you want strict mode to apply to multiple functions without needing to write "use strict" multiple times, use immediate function invocation:

// Good
(function() {
    "use strict";

    function doSomething() {
        // code
    }

    function doSomethingElse() {
        // code
    }    

}());

When assigning a value to a variable, use parentheses around a right-side expression that contains a comparison.

// Good
var flag = (i < count);

// Bad: Missing parentheses
var flag = i < count;

Use === and !== instead of == and != to avoid type coercion errors.

// Good
var same = (a === b);

// Bad: Using ==
var same = (a == b);

The ternary operator should be used only for assigning values conditionally and never as a shortcut for an if statement.

// Good
var value = condition ? value1 : value2;

// Bad: no assignment, should be an if statement
condition ? doSomething() : doSomethingElse();

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:

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

Blank spaces should be used in the following circumstances: