Please make sure that your editor is properly reading from the .editorconfig file located at the base of the repository.
Please take a few minutes and review our style guide:
The following provide a reasonable style and formatting guide for all Javascript produced at Message Systems. The most important take-away from this guide is: be consistent. A lot of effort has been made to keep this guide focused on style and formatting. However, conventions and techniques are inevitably part of things as well. These have been minimized as much as possible, as other documents are better suited to handle them.
Avoid single letter names outside of loops. Offer descriptive names.
// Bad
function q() {...}
// Good
function query() {...}
for (var i = 0; i < 10; i++) {
...
}
Use camelCase when naming objects, functions, and instances.
// Bad
var MYObject = {};
var my_string_variable = '';
var my-object-variable = {};
// Good
var myObject = {};
var myStringVariable = '';
var myObjectVariable = {};
Use PascalCase for class names.
// Bad
var superHero = function (options) {
this.name = options.name;
};
var reed = new superHero({ name:'Reed Richards' });
// Good
var SuperHero = function (options) {
this.name = options.name;
};
var reed = new SuperHero({ name:'Reed Richards' });
Do not treat "private" object properties as special with something like an underscore. If you need private properties, obtain them by closing over them in the constructor.
// Bad
this._ccNumber = '4111111111111111';
// Good
function AccountInfo(cardNumber) {
var cardNumber = cardNumber;
// initialization, &c.
return this;
}
var acct = new AccountInfo('4111111111111111');
If you are making a reference to this, use self (assuming a bind() function isn't used).
// Bad
function () {
var that = this;
return function () { console.log(that); };
}
// Good
function () {
var self = this;
return function () { console.log(self); };
}
You're not a minifier. Save yourself the headache of trying to be one.
// Bad
var q = function q(s) {
return document.querySelectorAll(s);
};
var i,a=[],els=q('#test');
for(i=0;i<els.length;i++){a.push(els[i]);}
Always use var to declare variables. Not doing so will result in global variables. Unintentional global variables lead to unexpected program behavior. Even if a new variable is meant to be global, you should still use var.
// Bad
food = 'pickle';
! function () {
food = 'hot dogs';
}();
// food = 'hot dogs'
// Good
var food = 'pickle';
! function () {
var food = 'hot dogs';
}();
// food = 'pickle'
When declaring multiple variables, use a single var declaration in the comma-first style. Improve readability by using line comments to break out groups of related variables.
// Bad
var buffer = [];
var counter = 0;
var ref;
var canRotate = true;
var hasResults = false;
var isMutable = false;
// Bad
var buffer = [],
counter = 0,
ref,
canRotate = true,
hasResults = false,
isMutable = false;
// Good
var buffer = []
, counter = 0
, ref
// Flags
, canRotate = true
, hasResults = false
, isMutable = false;
Declare unassigned variables last. (If you're splitting out groups of variables with line comments, declare unassigned variables at the end of whichever group they're in.)
// Bad
var ref, len,
items = getItems();
// Good
var items = getItems()
, len
, ref;
Initialize each variable as you declare it, if its value is available at declaration time and either is of primitive type, or can be expressed in a single (ideally short) line of code. If a variable needs to be initialized with the result of an expression spanning multiple lines, declare the variable without a definition and assign its value afterward.
// Bad
var ref
, len;
ref = things[0];
len = ref.length;
// Good
var ref = things[0]
, len = ref.length;
// Bad
var ref = things[0]
.map(function(item){
return item * 2;
})
.filter(function(item){
return (item % 2 === 0);
})
, len = ref.length;
// Good
var ref
, len;
ref = things[0]
.map(function(item){
return item * 2;
})
.filter(function(item){
return (item % 2 === 0);
});
len = ref.length;
Avoid variable hoisting: Declare variables at the top of their scope.
// Bad
var InsertRecord = function (data) {
validate();
notify.info('Inserting record');
var name = data.name;
if (name === 'test') {
return false;
} else {
return name;
}
};
// Good
var InsertRecord = function (data) {
var name = data.name;
validate();
notify.info('Inserting record');
if (name === 'test') {
return false;
} else {
return name;
}
};
Variable declarations get hoisted to the top of a scope by the Javascript interpreter. Assignments do not. This can lead to unexpected situations. More information about this can be found at Adequately Good (http://www.adequatelygood.com/2010/2/JavaScript-Scoping-and-Hoisting); below is an example from that article. The takeaway is: Declare your variables early. If you are in the habit of putting them at the top of their scope, you can avoid the problem.
function test() {
foo(); // TypeError "foo is not a function"
bar(); // "This will run!"
// Function expression assigned to local variable 'foo'
var foo = function () {
alert("This won't run!");
}
// Function declaration, given the name 'bar'
function bar() {
alert("This will run!");
}
}
test();
There are two categories of data types:
- Primitives: string, number, boolean, null, undefined
- Complex: object, array (really an object), function (also an object)
Primitive types are assigned and passed by value; complex types, by reference.
Use only single-quoted strings. (If you slip up and wrap a string in double quotes, never fear – JSHint will remind you.) Strings longer than 80 characters should be written across multiple lines using string concatenation. When building strings programmatically, use Array.join() instead of string concatenation. Don't build strings of HTML. Instead, just manipulate the DOM directly.
Use the literal syntax for array creation.
// Bad
var items = new Array();
// Good
var items = [];
Use Array.push() to add elements to the end of an array whose length you don't know.
// Bad
stack[stack.length] = 'element';
// Good
stack.push('element');
Clone arrays with Array.slice().
// Bad
var src = [1,2,3],
dst = src;
src[1] = 'string';
// dst = [1, 'string', 2]
// Bad
var src = [1,2,3],
dst = [];
for (var i, len = src.length; i < len; i++) {
dst[i] = src[i];
}
// Good
var src = [1,2,3]
, dst = src.slice();
Don't use "associative" Arrays. Use an Object, or hashes/maps.
// Bad
var items = [];
items['animal'] = 'dog';
items['mineral'] = 'shale';
// items.length == 0
// Good
var items = {};
items.animal = 'dog';
items.mineral = 'shale';
Use the literal syntax for object creation.
// Bad
var obj = new Object();
// Good
var obj = {};
Don't use reserved words as keys, even if you quote them.
// Bad
var Fig = {
class: 'food',
default: { flavor: 'strawberry' },
'private': true
};
// Good
var Newton = {
type: 'food',
defaults: { flavor: 'strawberry' },
hidden: true
};
It's completely acceptable to modify native object prototypes as long as the following rule is observed: Don't be stupid. Browsers with older versions of Javascript interpreters can often be augmented (in limited ways) to be compatible with newer flavors of the language through native object modification. Great care must be exercised however not to break or overwrite current or future functionality. Future functionality? Yes: Object.create(). An easy way not to break native objects is to add functionality conditionally:
if (typeof Object.create == 'undefined') {
Object.create = function (...) {
// Implementation...
}
}
When accessing object properties by literal name, use the dot notation. Reserve the bracket notation for when the property you're accessing is named by a variable's value.
var carrot = {
category: 'plant',
color: 'orange'
}
// Bad
var color = carrot['color'];
// Good
var color = carrot.color;
// Good
var propName = 'color';
var color = carrot[propName];
// Good
var carrot.getProp = function (prop) {
return this[prop];
}
Use /* ... */ for multiline comments.
// Bad
// No updates can be made to the resource during this operation as the
// bookkeepping for it will NOT be performed because of possible race
// conditions. All updates during this period will be ignored, so be
// sure to reflect this in the UX.
model.lock();
// Good
/*
* No updates can be made to the resource during this operation as the
* bookkeepping for it will NOT be performed because of possible race
* conditions. All updates during this period will be ignored, so be
* sure to reflect this in the UX.
*/
model.lock();
Use JSDoc to document functions, methods, &c.
// Good
/*
* Return an array whose (numeric) values are inverse of those in its argument.
*/
function invert(list) {
return list.map(function(i) { return i - (2 * i); });
};
// Better
/**
* Return an array whose (numeric) values are inverse of those in its argument.
* @param {number[]} list - An array of numeric values.
* @returns {number[]} An array of inverted values.
*/
function invert(list) {
return list.map(function(i) { return i - (2 * i); });
};
Use // for single line comments. Place them on a newline above the subject of the comment with a blank line above that. The blank line may be omitted when the comment directly follows a control structure. Capitalize the first letter of a comment.
// Bad
try {
options = argsParser[parseType](argv);
// get the module to execute and its partner output module
exe = options && require('./main-' + options.main);
out = options && require('./output/main-' + options.main + '-output').create(sysUtil, options.debug, options.quiet);
if (exe && out) { // only execute with a proper pairing
exe.exec(options, out, complete.bind(null, out, callback));
}
} catch (ex) { // create a generic/base 'out' module which can do the error printing
out = Output.create(sysUtil, argv.indexOf('--debug') != -1);
complete(out, callback, ex);
}
// Good
try {
options = argsParser[parseType](argv);
// Get the module to execute and its partner output module
exe = options && require('./main-' + options.main);
out = options && require('./output/main-' + options.main + '-output').create(sysUtil, options.debug, options.quiet);
// Only execute with a proper pairing
if (exe && out) {
exe.exec(options, out, complete.bind(null, out, callback))
}
} catch (ex) {
// Create a generic/base 'out' module which can do the error printing
out = Output.create(sysUtil, argv.indexOf('--debug') != -1)
complete(out, callback, ex)
}
End line comments should only be used when documenting long lists of variables or simple object properties.
// Good
var lock = false, // Mandatory lock indicator
, data = [] // Primary storage
, buffer = [] // Used for swaps or copies
, last = null // Points to last element of structure
, current = null; // Used for iterators
// Good
var struct = {
lock: false, // Mandatory lock indicator
data: [], // Primary storage
buffer: [], // Used for swaps or copies
last: null, // Points to last element of structure
current: null // Used for iterators
};
Use soft tabs set to 2 spaces (illustrated with dots, below).
// Bad
var fn = () {
....console.log('test');
};
// Good
var fn = () {
..console.log('test');
};
Place one space before the leading brace.
// Bad
var fn = (){
console.log('test');
};
// Good
var fn = () {
console.log('test');
};
// Bad
lookup.populate('Mr. Charles',{
age: 32,
job: JOB_SECURITY
});
// Good
lookup.populate('Mr. Charles', {
age: 32,
job: JOB_SECURITY
});
Javascript's semantics include optional automatic semicolon insertion. In theory, this allows less experienced programmers to more quickly get to grips with the language. In practice, this allows programmers of all experience levels the opportunity to discover the joy of seeing their code misbehave in various fashions both subtle and bizarre. When in doubt, insert a semicolon; if one doesn't belong there, JSHint will let you know.
// Bad
(function () {
var name = 'Ricky Bobby'
return name
})()
// Good
(function () {
var name = 'Ricky Bobby';
return name;
})();
Use braces with multi-line blocks. Ensure leading brace is on the same line.
// Bad
if (test)
return false;
// Good
if (test) {
return false;
}
// Bad
var fn = function() { return false; };
// Good
var fn = function() {
return false;
};
In a statement with multiple clauses (e.g. if/else if/else or try/catch/finally), introduce clauses following the first on the same line as the prior clause's closing brace.
// Bad
if (test) {
return thing.doThing();
}
else {
return undefined;
}
try {
thing.doThing();
}
catch (e) {
console.log('Thing couldn\'t do thing: ' + e);
}
// Good
if (test) {
return thing.doThing();
} else {
return undefined;
}
try {
thing.doThing();
} catch (e) {
console.log('Thing couldn\'t do thing: ' + e);
}
Use these expressions when declaring functions. The "!" of an immediately invoked function ensures that if a semicolon wasn't included on the previous statement, no execution error will occur.
// Anonymous function expression
var anonymous = function () {
return true;
}
// Named function expression
var fn = function named() {
return true;
}
// Immediately invoked function expressions
// Bad
(function() {
console.log('Page initialized');
})();
// Good
! function() {
console.log('Page Initialized');
}();
Never declare a function in a non-function block (if, while, etc). Instead, assign a function to a variable.
// Bad
if (enabled) {
function test() {
console.log('No');
}
}
// Good
if (enabled) {
var fn = function test() {
console.log('Yes!');
};
}
Never name a parameter arguments, as it will take precedence of the arguments object that is implicitly declared in every function scope.
// Bad
var fn = function nope(name, opts, arguments) { ... };
// Good
var fn = function yep(name, opts, args) { ... };
Favor explicit equality checks over normal ones. That means using === and !== over == and !=. When comparing a return value against a constant, place the constant on the right-hand side of the comparison operator.
// Bad: implicit "falsy" comparison
if (! thing.doThing()) {
// ...
}
// Bad: constant on left-hand side
if (false === thing.doThing()) {
// ...
}
// Good
if (thing.doThing() === false) {
// ...
}
Boolean evaluation of variables follows these rules:
- Objects evaluate to true.
- Undefined evaluates to false.
- Null evaluates to false.
- Booleans evaluate to the value of the boolean.
- Numbers evaluate to false if +/-0 or NaN, otherwise to true.
- Strings evaluate to false when empty (''), otherwise to true.
Use conditional evaluation shortcuts.
// Bad
if (name !== '') {
// ...
}
// Good
if (name) {
// ...
}
Used in moderation, libraries make our lives easier. Used profligately, they complicate life for everyone. Here follow some rules of thumb to help guide your judgment on the matter. Some things, such as checking types, testing whether an array is empty, or foreaching across an object's keys, can be trivially accomplished in native Javascript. Don't pull in a library just to do these things.
// Bad
var _ = require('lodash')
, items = []
, hasItems;
hasItems = (_.isEmpty(thing.doThing()) === false);
_.forEach(thing.things, function(value, key) {
items.push(value);
});
// Good
var items = []
, hasItems;
hasItems = (thing.doThing().length !== 0);
Object.keys(thing.things).forEach(function(key) {
var value = thing.things[key];
items.push(value);
});
On the other hand, don't be afraid to pull in a library to do complex things, such as deep-cloning an object, or testing emptiness of a variable whose value might be an object, an array, or undefined – ideally, of course, avoid proliferating such special cases by writing your code so that you can rely on value types; but, in cases where that's not possible, or where you're dealing with a value coming from code outside your control, bring in Lo-dash or another library, rather than spending your precious time reinventing the wheel. When you think about using a method from a library already present for other reasons, consider whether native Javascript can perform the same task without undue extra effort. If so, prefer the native Javascript method over that provided by the library; this promotes better modularity and, where possible to do so, helps avoid tight coupling with a given library. This makes it easier to replace that library later, if and when it becomes necessary to do so, and also reduces cognitive overhead for other developers working with your code.
var _ require('lodash')
, anArray = [1, 2, 3, 4, 5]
, anObject = {'foo': 1, 'bar': 2}
, anotherObject;
// No question of removing Lo-dash entirely:
anotherObject = _.cloneDeep(anObject);
// [...]
// Bad: gratuitous use of Lo-dash
_.forEach(anArray, function(val) {
console.log(val);
});
_.map(anObject, function(val, key) {
console.log(key + ' = ' + val);
});
// Good: native methods avoiding dependency
anArray.forEach(function(val) {
console.log(val);
});
Object.keys(anObject).map(function(key) {
var val = anObject[key];
console.log(key + ' = ' + val);
});
In general, avoid jQuery-style method chaining for readability reasons. Instead, use temporary variables to store intermediate results.
// Bad
anArray
.map(function(item) {
// ...
})
.filter(function(item) {
// ...
})
// Good
var mapping
, result;
mapping = anArray.map(function(item) {
// ...
});
result = mapping.filter(function(item) {
// ...
});