JavaScript Style Guide

This will have, may be, has been the official JavaScript style guide for developers of Symphony CMS.

Tabs vs. Spaces

Spaces are evil. Always use 4–space wide tabs while developing for Symphony CMS. Yes, I realise that the examples on this page use 4–space indentation and not tabs. Do what I say!

Semicolons

Apparently, some people don’t like using semicolons to terminate statements. Failing to do so may get you flayed.

Right

var value = 'example';

Wrong

var value = 'example'

Trailing whitespace

Just like you brush your teeth after every meal, clean up trailing whitespace in your JavaScript files before committing. Otherwise the rotten smell of careless neglect will eventually drive away contributors and/or co–workers.

Line length

Most reasonable text editors (Textmate and Sublime Text to name a couple) allow intelligent word-wrapping inside of your window. We suggest you use this instead of manually wrapping your lines to a fixed number of characters.

If you really must manually wrap some text, then do it to the standard 80 characters.

Quotes

Use single quotes, unless you are writing JSON.

Right

var value = 'example';

Wrong

var value = "example";

Braces

Your opening braces go on the same line as the statement. Also, don’t be afraid to use whitespace.

Right

if (true) {
    console.log('great');
}

Wrong

if (false)
{
    console.log('never');
}

Variable declarations

Don’t overuse var statements, always indent each variable on its own line.

Right

var foo = 1,
    bar = 'two';

Wrong

var foo = 1;
var bar = 'two';

Also wrong

var foo = 1, var bar = 'two';

Variable and property names

Variables and properties should use lower camel case capitalization. They should also be descriptive. Single-character variables and uncommon abbreviations should generally be avoided (may get you shot).

Right

var translatedString = Symphony.Language.Dictionary[string];

Wrong

var translated_string = Symphony.Language.Dictionary[string];

Murder

var ts = Symphony.Language.Dictionary[string];

Class names

Class names should be capitalized using upper camel case.

Right

function YourClass() { ... }

Wrong

function your_class() { ... }

Constants

Constants should be declared as regular variables or static class properties, using all uppercase letters.

Right

var SECOND = 1 * 1000;

Wrong

var second = 1 * 1000;

Object and Array creation

Use trailing commas and put short declarations on a single line. Only quote keys when your interpreter complains:

Right

var a = ['hello', 'world'];
var b = {
    good: 'code',
    'is generally': 'pretty',
};

Wrong

var a = [
  'hello', 'world'
];
var b = {"good": 'code'
        , is generally: 'pretty'
        };

Conditions

Any non–trivial conditions should be assigned to a descriptive variable:

Right

var isAuthorized = (user.isAdmin() || user.isModerator());

if (isAuthorized) {
    console.log('winning');
}

Wrong

if (user.isAdmin() || user.isModerator()) {
    console.log('losing');
}

Function length

Keep your functions short. A good function fits on a slide that the people in the last row of a big room can comfortably read. So don’t count on them having perfect vision and limit yourself to ~10 lines of code per function.

Return statements

To avoid deep nesting of if–statements, always return a functions value as early as possible.

Right

function isPercentage(val) {
    if (val < 0) {
        return false;
    }

    if (val > 100) {
        return false;
    }

    return true;
}

Wrong

function isPercentage(val) {
    if (val >= 0) {
        if (val < 100) {
            return true;
        } else {
            return false;
        }
    } else {
        return false;
    }
}

Or for this particular example it may also be fine to shorten things even further:

function isPercentage(val) {
    var isInRange = (val >= 0 && val <= 100);

    return isInRange;
}

Else statements

Your else and else if statements should find themselves on a new line, and not on the same line as a brace.

Right

// We don't care:
if (val < 100) {
    return false;
}

// Value is in range:
else {
    return true;
}

Wrong

// We don't care:
if (val < 100) {
    return false;
} else {
    // Value is in range:
    return true;
}

Named closures

Feel free to give your closures a name. It shows that you care about them, and will produce better stack traces:

Right

req.on('end', function onEnd() {
    console.log('winning');
});

Wrong

req.on('end', function() {
    console.log('failing');
});