1) Naming


Variables and properties referring to jQuery element objects are prefixed with $

* @param {string} selector The jQuery selector for elements to apply
*     fanciness to.
function doSomethingFancy(selector) {
 var $elements = $(selector);
 // do something fancy with $elements ...

2) File names


3) Whitespace and Code Formatting

Use 4-space indenting for all code. Do not use tabs.

if/else/for/while/try always have braces and always go on multiple lines, with the opening brace on the same line

Braces should always be used on blocks.

  if (true)
  if (true) {

else/else if/catch go on the same line as the brace.

  if (blah) {
  } else {

Extra indentation should be used to clearly distinguish multiline conditionals from the following block of code (PEP8 addresses this for our Python code).

  if (someReallyLongBooleanVariableIMeanReallyLong &&
someOtherBoolean) {
return "monkeys";

  if (someReallyLongBooleanVariableIMeanReallyLong &&
someOtherBoolean) {
return "monkeys";

4) Line length

Lines should not exceed 79 characters.
This is consistent with our Python style guide, which adheres to PEP8.

5) Equality

Strict equality checks using === should be used in favor of == due to the numerous oddities related to JavaScript’s type coercion.

Examples where == can be confusing (all of the following statements evaluate to true):

Boolean('0') == true

'0' != true

0 != null

0 == []

0 == false

Boolean(null) == false

null != true

null != false

Boolean(undefined) == false

undefined != true

undefined != false

Boolean([]) == true

[] != true

[] == false

[[]] == false

Boolean({}) == true

{} != true

{} != false

The only valid use of == is for comparing against null and undefined at the same time.

// Check null and undefined, but distinguish between other falsey values
if (someVariable == null) {

Though, in most cases, other falsey values should also be included and the above can be simplified to the preferred:

if (!someVariable) {

6) Strings

Strings should use double quotes (“) instead of single quotes (‘)

7) Method and property visibility

Private methods and properties (in files, classes, and namespaces) should be named with a leading underscore.

While we do not currently use any compilers to enforce this, clients of an API or class are expected to respect these conventions.

example of some-module.js:

function _PrivateClass() {
   // should not be instantiated outside of this file

function PublicClass(param) {
   this.publicMember = param;
   this._privateMember = new _PrivateClass();

var x = new _PrivateClass();  // OK - we’re in the same file.
var y = new PublicClass();  // OK
var z = y._privateMember;  // NOT OK!

Rationale: leading underscores for private methods and properties is consistent with the styles used in numerous JavaScript libraries, many of which we include in our code base (e.g. Backbone). It is also consistent with our Python style guide, lowering the mental effort for developers to switch between the two.

8) Array and Object literals

Always use [] and {} style literals to initialize arrays and objects, instead of the Array and Object constructor.

Array constructors are error-prone due to their arguments.

// Length is 3.

// Length is 2.
var a2 = new Array(x1, x2);

var a3 = new Array(x1);

// Length is 0.
var a4 = new Array();



var a = [x1, x2, x3];
var a2 = [x1, x2];
var a3 = [x1];
var a4 = [];


9) Inline Comments.

Inline style comments should be of the // variety, not the /* */ variety.

10) Top level file and class comments

All files and classes should have JSDoc comments.

JSDoc can be parsed by a number of open source tools, and must be well-formed.



Top-level comments:
The top level file comment is designed to orient readers unfamiliar with the code to what is in this file and any other disclaimers clients of the code should be given. It should provide a description of the file's contents and any dependencies or compatibility information. As an example:

* Various components to handle management of lists of coaches for
* the profile page.

* These utilities were not written to be a general purpose utility
* for the entire code base, but has been optimized with the
* assumption that the Profile namespace is fully loaded.

Class comments:
Classes must be documented with a description, and appropriate type tags (see “Methods and properties” comments for more information on types on the constructor.

* Class making something fun and easy.
function SomeFunClass(arg1, arg2) {
 // ...

11) Methods and properties comments

All non-trivial methods and properties should also have JSDoc comments.
Type annotations are strongly encouraged; if there is even a slight chance that the type will be ambiguous to future readers, put in a type annotation.

Type annotations are based on the ES4/JS2 type system, and are documented in the Google JavaScript style guide.

@param and @return type annotations that have comments that do not fit on one line wrap to the next line and indent 4 spaces.


* A UI component allows users to select badges from their full list
* of earned badges, displaying them in a container.
* Expects a Badges.BadgeList as a model.
Badges.DisplayCase = Backbone.View.extend({
    * Whether or not this is currently in edit mode and the full
    * badge list is visible.
   editing: false,

    * The full user badge list available to pick from when in edit mode.
    * @type {Badges.UserBadgeList}
   fullBadgeList: null,

    * Enters "edit mode" where badges can be added/removed.
    * @param {number=} index Optional index of the slot in the display-case
    *     to be edited. Defaults to the first available slot, or if none
    *     are available, the last used slot.
    * @return {Badges.DisplayCase} This same instance so calls can be
    *     chained.
   edit: function(index) {

12) Use “$” for jQuery

We use $ as the jQuery identifier, as opposed to typing out jQuery in full.

jQuery(".some-class span").hide();

$(".some-class span").hide();

13) Avoid href="#" for javascript triggers

When you want a link-like thing rather than a button to trigger a javascript operation, rather than going to a new address.

Here's a discussion on Stack Overflow about options:


<a href="#">Flag</a>

Acceptable (if not totally "Good"): <a href="javascript:void 0">Flag</a>

Subpages (1): Backbone example