Kleenheat JavaScript Style Guide

1. Introduction

These guidelines are organized as simple recommendations prefixed with the terms DO, CONSIDER, AVOID, and DO NOT.

2. Layout

2.1 Files

DO use a separate file for each component.

DO include a top-level comment naming and describing the component.

/** 
 * Localization
 * Provides localization functions and an array of localized strings.
 */

var Localization = function() {
}

2.2 Use strict mode

DO use strict mode.

(function ($) {
    'use strict';
    /* bootstrap the page */
}(window.jQuery));

2.3 Braces

DO follow the Kernighan and Ritchie style (Egyptian Brackets) for non-empty blocks and block-like constructs.

var Localization = function() {
    constructor() {}

    method(foo) {
        if (condition(foo)) {
            try {
                something();
            } catch (err) {
                recover();
            }
        }
    }
}

while (condition)
{
    condition = something();
}

DO wrap a single-line block of code in braces, and DO keep the block on its own line.

while (condition) {
    condition = something();
}

while (condition)
      condition = something();

while (condition) { condition = something(); }

while (condition) condition = something();

2.4 Indenting

DO use four spaces as indentation.

2.5 Lines

DO write only one statement per line.

DO use an 80-character line length wherever possible.

DO use a semi-colon to terminate every line. Do not rely on automatic semi-colon insertion.

3. Comments

3.1 Documentation

DO document each component and each function, even if private in scope.

3.2 Lines

DO place a comment on its own line, before the line of code to which it relates.

// Prices are shown using Australian dollars, regardless of current user’s culture.
var options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
var text = date.toLocaleDateString('en-AU', options);

3.3 Language

DO use American English for writing comments.

Color
Center
Normalize

Colour
Centre
Normalise

4. General style

4.1 Conditional statements

DO use parentheses to make an evaluation apparent.

var active = (account.Status === 'Active');

var active = account.Status === 'Active';

4.2 If Statements

AVOID comparison to true or false.

if (customer.isValid()) {
}

while (!finished) {
}

if (customer.isValid() === true) {
}

while (finished === false) {
}

CONSIDER removing a redundant else statement.

var getName = function(customer) {
    if (customer !== null) {
        return customer.name;
    }
    return "";
}

var getName = function(customer) {
    if (customer !== null) {
        return customer.name;
    } else {
        return "";
    }
}

4.3 Return statements

AVOID nesting by returning a value at the earliest opportunity.

var getPromotion = function(code) {
    if (!code) {
        return null;
    }
    var promotion = // get from server
    if (!promotion) {
        return null;
    }
    if (!promotion.isCurrent()) {
        return null;
    }
    return promotion;
}

var getPromotion = function(code) {
    if (code) {
        Promotion promotion = // get from server
        if (promotion) {
            if (promotion.isCurrent()) {
                return promotion;
            }
        }
    }
    return null;
}

5. Naming

5.1 Language

DO use American English for naming variables.

var color;
var center;
var normalize;

var colour;
var centre;
var normalise;

5.2 Classes

DO use PascalCase for class names.

var BaseForm = function ($, $form, settings) {
}

5.2 Functions

DO use camelCase for function names.

var getTitle = function () {
    return 'Title';
}

5.3 Constants

DO use UPPERCASE for the name of constants.

var PAGE_SIZE = 20;

6. Variables

6.1 Variable declarations

DO use var.

DO NOT use const or let.

DO use a new line for each variable declaration.

var title;
var price;

var title, price;

6.2 Object declarations

DO use {} to declare new object.

var robot = {
    name: 'Wall-E',
};

var robot = {};
robot.name = 'Wall-E';

var robot = new Object();
robot.name = 'Wall-E';

DO use a trailing comma whenever there is a line break between the final element and the closing brace.

var obj = {
    foo,
    bar,
    method() { return this.foo + this.bar; },
};

6.3 Array declarations

DO use [] to declare a new array.

var robots = [ 'Wall-E', 'Eve' ];

var robots = new Array( 'Wall-E', 'Eve' );

var robots = new Array();
robots[0] = 'Wall-E';
robots[1] = 'Eve';

DO use a trailing comma whenever there is a line break between the final element and the closing bracket.

var values = [
    'first value',
    'second value',
];

6.4 String declarations

DO use an apostrophe (') rather than a quotation mark (") to define a string.

var name = 'Daffy Duck';
var html = '<p class="title">Title</p>';

var name = "Daffy Duck";
var html = "<p class=\"title\">Title</p>";

7. Operations

7.1 Equivalence

DO use === and !== for testing equality.

var test = ("1" === 1); // false

var test = ("1" == 1); // true

7.2 Null-coalescing operator

DO use the null-coalescing operator.

var text = value || 'fallback';

if (value) {
    var text = value;
} else {
    var text = 'fallback';
}

7.3 Conditional (ternary) operator

DO use the conditional operator.

var text = (grade >= 50) ? 'pass' : 'fail';

if (grade >= 50) {
    var text = 'pass';
} else {
    var text = 'fail';
}

7.4 Eval

DO NOT use the eval() function.

7.5 Try-catch blocks

DO NOT use an empty catch block—at least document the reason why error handling is not required.

try {
    something();
} catch (ok) {
    // it's not numeric; that's fine, just continue
}

try {
    something();
} catch (error) {}

8. jQuery

8.1 Naming

DO prefix a variable name with ‘$’ if it represents a jQuery object.

var $body = $(document.body);
var $sidebar = $body.find('.sidebar');

8.2 Exists

DO use length to test whether an element exists.

if ($('.sidebar').length) {
    /* The sidebar exists. */
}

if ($('.sidebar')[0]) {
    /* The sidebar exists. */
}