This document was created to serve as a universal JavaScript style guide to aid in collaboration as well as to keep my own code internally consistent.
The purpose of this guide is to provide a set of standards for the writing and design of Javascript code. Implementation of this guide will provide uniformity in code style and formatting in order to improve the quality of the code we are writing, making it consistent, readable, and maintainable. Ultimately code should appear as if it were written by one person. It should be easy for any third party to understand, use, and contribute to your code. Violations to this guide are allowed if they enhance readability.
Inspiration for this guide was taken from similar style guides such as those by idiomatic, airbnb, jQuery, Google, Aloha, Dojo and other sources around the web. This document, like anything I make, is mostly an amalgamation of other people's wonderful ideas wrapped up in one place for my purposes. Efforts have been made to find a balance between clear/readable and compact/efficient. Of course, in the end this is my personally preferred set of coding conventions, and you're free to write your programs as you see fit within your own projects. If you see any problems with it, or think you could help to improve it, feel free to modify this document and submit a pull request.
A certain amount of familiarity with the JavaScript language and programming in general will be assumed throughout.
This is a living document. Expect it to be modified at any time to meet the current standards in practice in projects it may be applicable to.
- Foreword
- Conventions - Linting
- Choices - Indentation - Quotation
- Naming
- Declarations - Literals - Variables
- Formatting - Commas - Whitespace - Loops
- Comments
- Further
- HTML/CSS - (CSS)(#css)
- Afterword
-
1.1 This is a style guide for JavaScript. Despite the availability of compile to js languages, all efforts should be made to keep our codebase purely in JavaScript.
-
1.2 In keeping with this, we should also minimize our use of external libraries. This is for the sake of simplicity in reasoning about the code, as well as forcing us to actually know what we're doing and reducing the number of bugs caused by third-party code. The majority of our code should be written by us.
-
1.3 Write with the intent of producing readable code. Expect that someone else will have to read and understand your code at some point. Use the correct whitespace and formatting to ensure readabililty. Finished code will be minified, so just write nicely.
-
1.4 If it wasn't already obvious from the webpage you're likely viewing this from, our projects will be managed through github. If you aren't familiar with github, here's a quick primer. You should have a basic understanding of git, it's simple and useful.
-
1.5 Use JSHint for linting. Linting helps to detect and fix errors, and is considered good practice.
Much like the oxford comma, there are many things within JavaScript that are simply a matter of preference. I've made these choices in regards to my own preferences when working with JavaScript. These are things that are entirely at the discretion of the project authors. JavaScript handles them exactly the same way internally. The only thing that is important, is consistency. Pick one and stick to it for the entire project. For your consideration:
- 2.1 Indentation choice. Whether you use real tabs or soft indents(spaces), and, if you should choose soft tabs, whether you indent by 2 or 4 spaces. Crockford and others argue against the use of tabs for indentation, as there is no standard way of handling tabstops. Indenting by spaces can increase filesize in a large project, but this is mitigated in the minification process, and should not be a concern. Never mix tabs and spaces.
Opt for the use of soft tabs for indentation.
- 2.2 Whether you use single or double quotations. If double quotations are used, single quotes are allowed for inner quotes, and vice versa for single quotes.
Single quote style is preferred, with double quotes within strings. The majority of javascript code on github uses this style.
-
3.1 Names should be written in short, simple, descriptive English.
-
3.2 Use CamelCase for class names and mixedCase for method and property names.
-
3.3 Names should be easy to understand. Favor naming to functionality over values.
-
3.4 Avoid names that are misleading, or have multiple meanings.
-
3.5 Don't obfuscate names, for example by removing all vowels. Understandable abbreviations are acceptable, but in general should be avoided. The main point is to keep it humanly readable.
// BAD
var objPosX = 0;
// GOOD
var objectPositionX = 0;- 3.6 Avoid magic numbers, use named constants. Program for the future. Constants should be named in all caps, with underscores used to separate words.
var SOME_CONSTANT = 123.45;// BAD
unitPos_X
// GOOD
unitPositionX-
3.8 Method names should be verbs.
-
3.9 Methods and properties that are determined to be private should be prepended with an underscore (_)
-
3.10 Use is or has/can/should for boolean variables and methods. Avoid negated booleans.
// BAD
var isNotThing = true;
// GOOD
var isThing = false;-
3.11 Use compute when naming functions that perform computations.
-
3.12 Use find when naming functions that looks up some value.
-
3.13 Methods may be named after what they return. If the return void instead of an object then after what they do.
-
3.14 Collections should be plural.
// BAD
var animalList = [];
// GOOD
var animals = [];-
3.15 Iterators should be named i, j, k, etc. They should be defined in the loop constructor. This is significantly more readable than anticipating variable hoisting.
-
3.16 Avoid checking for array length in every iteration of a loop. Set another variable to hold the length in the loop constructor.
var l = someArray.length;
for(var i = 0; i < l; i++) {
doSomethingTo(someArray[i]);
}- 3.17 Generic variables should have the same name as their type.
//where topic is of type Topic
setTopic(topic)- 3.18 Initialization methods should be named init().
// BAD
initialize()
initializeSomething()
start()
run()
// GOOD
init()
initSidebar()- 3.19 Don’t use “that” to refer to an outer “this”. Use the name of the class instead (with first char lowercased).
var MyObject = Class.extend({
_constructor: function() {
// BAD
var that = this;
setTimeout(function() {
console.log(that.name + ' done.');
};
// GOOD
var myObject = this;
setTimeout(function() {
console.log(myObject.name + ' done.');
};
}
});- 4.1 Use literal syntax for objects and arrays
// BAD
var squid = new Object();
var reefs = new Array();
// GOOD
var squid = {};
var reefs = [];- 4.2 Initialize variables where they're declared, even if it's a null declaration.
// BAD
var someObj, someArr;
// GOOD
var someObject = {};
var someArray = [];-
5.1 ALWAYS use brackets and semicolons where applicable. Never rely on automatic insertion.
-
5.2 Related variables of the same type should be declared in a common statement. Unrelated variables or those of different type must have a separate var declaration.
// BAD
var someObj, anArray, counter, height;
// GOOD
var someObject = {};
var anArray = [];
var counter, height;- 5.3 Floating point constants should always be named with at least one number before and after the decimal point.
var position.x = 0.0;-
5.4 An effort should be made to contain scope for the purpose of keeping variables alive for the smallest amount of time possible.
-
5.5 Commas should be followed by a space or newline.
// BAD
shape = new THREE.BoxGeometry(width,height,depth);
// GOOD
shape = new THREE.BoxGeometry(width, height, depth);- 5.6 No preceding space on commas or semicolons.
// BAD
someObject.functionCall( arg1 , arg2 , arg3 );
// GOOD
someObject.functionCall(arg1, arg2, arg3);- 5.7 No whitespace at eol or on blank lines.
//this is important- 5.8 Assignment operators should have a space on either side.
// BAD
frame=i;
// GOOD
frame = i;- 5.9 Unary operators(!, ++) should not have a space next to their operator.
// BAD
balls = - Math.RandInt(10,160);
ballCount ++;
// GOOD
balls = -Math.RandInt(10, 160);
ballCount++;-
5.10 Semicolons used as statement terminators should be followed by a newline.
-
5.11 Avoid filler spaces, especially in empty constructs such as {}, [], and function().
-
5.12 If statements, for loops, while loops, and function declarations should have their opening brace on the same line, separated by a space.
// BAD
if(condition){functionCall();}
if(condition)
{
functionCall();
}
// GOOD
if(condition) {
functionCall();
}- 5.13 Ternary conditionals should have a space on either side of their operators.
condition ? expression1 : expression2;-
5.14 Logical units within a block should be separated by one blank line. Do not use multiple consecutive blank lines in your programs.
-
5.15 There is no hard limit on line length but be reasonable. If you need a number then 80 or 120 characters, including whitespace, are common restrictions.
-
5.16 Split line positioning for expressions and methods:
var someExpression = Expression1
+ Expression2
+ Expression3
;
var o = someObject.get(
Expression1,
Expression2,
Expression3
);-
6.1 It is often said that good code is its own documentation. This is a wonderful ideal but, since we are not the golden gods of clear and readable code, we'll use comments where applicable.
-
6.2 Comments should be concise and descriptive. Only write what you need, no more. We aren't going to run out of ink, but if you comment every single line you're an asshole. Prefer writing for readability over commenting on functionality.
-
6.3 All comments should be written in American English for the sake of uniformity.
-
6.4 Comments should be indented relative to their position in the code, above the code the describe. Single line comments to the right of the code are also acceptable.
-
6.5 Collections should be commented describing the common elements.
-
6.6 Large blocks should be commented.
-
6.7 Inline comments should be avoided.
-
6.8 Comments found to be in violation of these rules will be pruned with extreme prejudice.
- 7.1 When building strings programmatically, use template strings.
//bad
function sayHi(name) {
return 'How are you, ' + name + '?';
}
//good
function sayHi(name) {
return `How are you, ${name}?`;
}-
7.2 Always use strict equality checks (===). The only situation where you would use a loose inequality operator (==) is if you are checking for something that could be null or undefined by way of == null, such as in the case of uninitialized variables.
-
7.3 You can emulate enums in the style of C by using a single object as a holder for all your constants, naturally written in all caps.
var someEnum {
ONE_THING: 0,
ANOTHER_THING: 1,
THIRD_THING: 2
}- 7.4 Singletons are useful for objects that have state.
var pezDispenser = (function() {
var amount = 20;
return {
dispense: function() {
if (amount > 0) }
amount -= 1;
alert('delicious pez!');
} else {
alert('no more pez!');
}
}
};
}());
pezDispenser.dispense();Simply name the function and refrain from invoking it immediately and you have what amounts to a constructor.
-
7.5 Don't use eval(), okay?
-
7.6 Don't worry about using the new keyword. I mean, use it, obviously, just don't be concerned that you're doing something 'bad'.
-
7.7 If you're going to use the delete operator, make sure you understand how it works. In general it is used to remove object properties. NOT for variables, function arguments, or function identifiers. If you need to free up a reference for GC then setting it to null would be the preferred notation. Setting an object to null will also clean up all of the properties of that object.
-
7.8 Don't pass strings to setInterval() or setTimeout(). Passing in strings is both painfully slow and potentially insecure. If you pass in a string, javascript will hand it to the function constructor to be converted into a new function. Instead pass in a function reference or an anonymous function.
-
HTML formatting should be compact yet readable. Formal definitions of HTML style yet to be decided. Reference existing files and make good decisions.
CSS files follow basically the same set of conventions as javascript. - Each selector is on a new line - Opening curly braces are preceded by a space - Key value pairs have a space after the colon - Every block is followed by an empty new line
.className {
color: #800080;
}
.className,
#anId {
color: #00CA00;
}
Thanks for reading! Feel free to contact me if there's anything you'd like to say.
This work is licensed under a Creative Commons Attribution 4.0 International License.
