A style guide is a set of standards to be followed during the writing and designing of code. The implementation of a style guide provides uniformity in code style and formatting. Style guides typically cover guidelines regarding indentation (tabs vs. spaces), variable naming conventions, where best to apply whitespace, and so on.
When you write code you have to think about who will be using it and maintaining it. This most likely will not always be you, and this is especially true if you're working in a team.
Following a style guide helps improve the overall quality of the code you write. This will help facilitate other developers with maintenance and will save time when making changes, adding new features or just when reading it over (code intake).
Readable source code is easier for us to understand as well. It's easier to browse, locate and fix bugs in and more easy to optimize. It can also give us a clearer picture of how the code fits into a larger body of work.
Being consistent will reduce lead time required to understand your code, and if created in a team, will look like one person wrote it. This clarifies how changes and updates to an implementation should be styled or structured.
This is a guide for writing consistent and aesthetically pleasing JavaScript code. It is inspired by Google's style-guides that they use for open source projects, along with some logical reasoning.
There is a .jscsrc file which enforces these rules as closely as possible. You can either use that and adjust it, or use this script to make your own. You can install JSCS via NPM using npm install jscs -g. There are also a large number of plug-ins available for use in your favorite editor or task manager.
- Atom plugin: https://atom.io/packages/linter-jscs
- Brackets Extension: https://github.com/globexdesigns/brackets-jscs
- Grunt task: https://github.com/jscs-dev/grunt-jscs/
- Gulp task: https://github.com/jscs-dev/gulp-jscs/
- Overcommit Git pre-commit hook manager: https://github.com/brigade/overcommit/
- SublimeText 3 Plugin: https://github.com/SublimeLinter/SublimeLinter-jscs/
- Syntastic VIM Plugin: https://github.com/scrooloose/syntastic/blob/master/syntax_checkers/javascript/jscs.vim/
- Web Essentials for Visual Studio 2013: https://github.com/madskristensen/WebEssentials2013/
- IntelliJ IDEA, RubyMine, WebStorm, PhpStorm, PyCharm plugin: https://www.jetbrains.com/webstorm/help/jscs.html
This guide was created by Joseph Szczesniak and is licensed under the is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. You are encouraged to fork this repository and make adjustments according to your preferences.
Limit your lines to 80 characters. This is to maintain human readability, and to train you to keep your logic short and concise. Your editor should have a line to show this in the editor. We do not enforce this in comments or regex statements.
To improve human readability you should use spaces to indent your code. Different editors display tabs differently, and using tabs requires you to know what the indentation of a tab is going to look like, and require it to always be consistent. Therefore we will not use tabs. 2 spaces is preferred because it is quicker and leaves code more compressed horizontally. It is also very similar to the old days of using 2 spaces after a period, so that's neat.
Save time and configure your editor to insert 2 spaces when you press the tab button to save you from having to press the space bar twice. Also configure auto indenting to use 2 spaces, and then you can adjust code quickly.
Even though semicolons are technically optional in JavaScript, it is important that you use them. Interpreters can make mistakes without them.
Valid
var a = 1;
var fn = function () {
//...
};
Invalid
var a = 1
var fn = function () {
//...
}
Example:
// define a function
var fn = function () {
//...
} // semicolon missing at this line
// then execute some code inside a closure
(function () {
//...
})();
This will be interpreted as:
var fn = function () {
//...
}(function () {
//...
})();
Block statements (the keywords do, for, if, else, switch, case, try, catch, void, while, with, and function) do not require semicolons.
Valid
if (x) {
x++;
}
Invalid
if (x) {
x++;
};
Not using curly braces can lead to errors. Block statements (the keywords do, for, if, else, switch, case, try, catch, void, while, with, and function) should have braces. Curly braces must also start on the same line as the statement to avoid undefined errors. If you must split parameters onto new lines, use four spaces and keep curly braces on the same line as the final parameter.
Valid
if (x) {
x++;
}
Invalid
if (x) x++;
Invalid
if (x)
{
x++;
}
When writing if statements, else must be on the same line as the ending curly brace of the if.
Valid
if (x < 0) {
x++;
} else {
x--;
}
Invalid
if (x < 0) {
x++;
}
else {
x--;
}
Always use single quotes except when using JSON. JSON strings must be double quoted.
Valid
var x = 'x';
Invalid
var x = "x";
Valid
var jsonString = '{"key1":"value1"}';
Use single quotes to create strings. If you need to break a string into multiple lines, use + to concatenate.
Valid
var x = 'multi' +
'line';
var y = 'single line';
Invalid
var x = "multi \
line";
Remove all trailing whitespace. Programmers who have gotten fast will use the end key or cmd + arrow keys to navigate to the end of the current line. If you have whitespace at the end of your code, this is frustrating.
Always use var when declaring variables. When a comma is forgotten, JavaScript will add a semicolon, thus elevating a var-less property to the global scope. This may have unintended consequences, so just don't do it.
Valid
var a = require('a');
var b = require('b');
var x = 1;
var y = 2;
for (var i = 0, var j = arr.length; i < j; i++) {}
Invalid
var a = require('a'),
b = require('b');
var x = 1,
y = 2;
var x, y = 2, z;
for (i = 0, j = arr.length; i < j; i++) {}
Always put a single space after block statements (the keywords do, for, if, else, switch, case, try, catch, void, while, with, and function). Binary operators (=, ,, +, -, /, *, ==, ===, !=, !==, etc.) should also be surrounded with spaces. In addition, put space before and after the ? or : in conditional expressions.
The opening/closing braces and curly braces after keywords, block statements, and literal objects should also have spacing.
Valid
if (x) {
x++;
}
x !== y;
var a = b ? c : d;
Invalid
if(x) {
x++;
}
x!== y;
x !==y;
x!==y;
var a = b? c : d;
var a = b ?c : d;
var a = b ? c: d;
var a = b ? c :d;
Object and Array brackets, parenthesis, and line breaks should not contain spaces. Braces that belong to a function should not have a spaces. Likewise, when you call and expression, do not use spaces.
Valid
var x = {a: {b: 1}};
var x = [[1]];
var x = (1 + 2) * 3;
var x = a[1];
function(){}
foo();
Invalid
var x = { a: { b: 1 } };
var x = [ [ 1 ] ];
var x = ( 1 + 2 );
var x = a[ 1 ];
function () {}
foo ();
In addition, there should be no space after object keys, but before their values.
Valid
var y = {
a: 1,
b: 2
}
var x = {a: 1};
Invalid
var y = {
a:1,
b :2
}
var x = {a : 1};
There is no need for multiple line breaks. Also, don't put line breaks after block statements (the keywords do, for, if, else, switch, case, try, catch, void, while, with, and function).
Valid
x++;
if (cond){
foo();
}
Invalid
x++;
if (cond)
{
foo();
}
Constants should always be in uppercase, and use underscores to separate out words. If you're using ECMA6 you should also use the const keyword. Do not use object properties as constants, only use primitives. JavaScript will not protect your properties from being overwritten.
Valid
const MAX_NUMBER_OF_ATTEMPTS = 5;
Invalid
const maxNumberOfAttempts = 5;
Invalid
const MY_OBJECT = { key: "value"};
All public variables should be camelCase. The leading character is lowercase, and all other words should be capitalized. If a variable is private, start it with an underscore. Trailing underscores are acceptable.
Valid
var camelCase = 0;
var CamelCase = 1;
var _camelCase = 2;
var camelCase_ = 3;
Invalid
var lower_case = 1;
var Mixed_case = 2;
var mixed_Case = 3;
Constructors should always be capitalized.
Valid
var a = new Car();
Invalid
var a = new car();
Valid
x = y ? 1 : 2;
x = y ?
1 : 2;
Invalid
x = y
? 1 : 2;
Unary operators should be "stuck to the right". There should not be a space between the unary operators and the variables on which they're being used.
Valid
x = !y; y = ++z;
Invalid
x = ! y; y = ++ z;
Parameters should be separated with a comma and a space for readability.
If you have to write parameters on separate lines, use two spaces to indent them. Then, the following code should be indented another two spaces to preserve readability.
Valid
function (paramOne, paramTwo,
paramThree) {
x++;
}
Invalid
function (paramOne,paramTwo,
paramThree) {
x++;
}
Valid
var a = b.c;
var a = b[c];
var a = b[c.d];
var a = b[1];
var a = b.while; // reserved words can be property names in ES5
Invalid
var a = b['c'];
Use of the with statement is not recommended, as it may be the source of confusing bugs and compatibility issues.
Invalid
with (x) {
prop++;
}
Coming soon