This document attempts to codify the JavaScript, HTML and CSS style rules for Fauxton. This has been patched together from a few sources, including Pootle's style guide, Google JS style guide, and from reverse-engineering our own codebase.
This is intended to be a living document: any disagreements about style should be brought to the community via the mailing list, discussed, agreed upon and documented here.
Note: We have JSHint running as a grunt task which will catch the more egregious errors (missing vars
, missing semicolons etc). See the Gruntfile.js
for the settings being used.
function
and the (
(left parenthesis). Similarly, for named functions there should be a space between the function name myFunction
and the opening parenthesis.;
(semicolon) in the control part of a for statement should be followed with a space.,
(comma) should be followed with whitespace.Use '
single quote character for strings, because HTML markup uses "
. Eg. var greeting = 'Hello World!'
;
When using parseInt
always explicitly include the second radix argument (usually 10).
myVariable
, myMethod
MyModel
, MyView
$
. For example:var $ul = $('#myList');
js-
. This way it’s clear the separation between class selectors that deal with presentation (CSS) and functionality (JavaScript).this.$("...")
to target elements, even IDs.Use Underscore's more concise looping methods (_.each
, _.filter
) over plain vanilla for
loops.
Control statements such as if
, while
, switch
should follow these rules:
{
(left curly brace) should be at the end of the line that begins the compound statement.}
(right curly brace) should begin a line and be indented to align with the beginning of the line containing the matching {
(left curly brace).if
or while
statement. This makes it easier to add statements without accidentally introducing bugs.Once you have create a variable and assigned a value, it is set as a type, stick with that type for that variable. This has performance benefits as well as making it easier for someone to understand your code.
Bad:
var greeting = 'Hello World!'; greeting = function () { return 'Goodbye World'; };
Special cases for null
and undefined
since they‘re their own type. It’s fine to assign a new value to an undefined or null var.
To maintain calling context, favour _.bind
over storing a reference to this
. If you do, use that
as a var name (var that = this;
)
Do not modify any native objects' prototype. eg. Array.prototype
.
Avoid using constructors for the built-in object types: Number, String, Boolean, Array, Object.
Number:
var x = 10; // good var x = new Number(10); // bad
String:
var greeting = 'Hello'; // good var greeting = new String('Hello'); // bad
Boolean:
var yes = true; // good var yes = new Boolean(1); // bad
Array:
var myList = new Array(1, 2, 3); // nope var myList = [1, 2, 3]; // yay!
Object:
var myObj = { size: 10 }; // hurrah! var myObj = new Object(); // boooo!
Use object literal notation for map/hash/associative arrays.
if
statementsif (condition) { statements } if (condition) { statements } else { statements } if (condition) { statements } else if (condition) { statements } else { statements }
for
statementsAs mentioned above, using Underscore's looping methods is favoured here.
for (initialization; condition; update) { statements; } for (variable in object) { if (condition) { statements } }
switch
statementsswitch (condition) { case 1: statements break; case 2: statements break; default: statements }
function myFunction () { // stuff! } function anotherFunction (firstParam, secondParam, thirdParam) { // stuff! } var yetAnotherFunction = function (firstParam) { // stuff! } var anonymousFunction = function () { // more stuff! }
In Fauxton, all our HTML documents are all Underscore templates so this section contains a few Underscore-related style recommendations as well.
-
), like my-class
and fixed-header
.js-
prefix. Note: these should NOT be styled; they should be used for JS hooks only.my_template.html
.<%- %>
over <%= %>
.We use Less to generate our CSS.
.my-class { /* rules here */ }
-
), like .my-class
and .fixed-header
.