Javascript Coding Standards

Phabricator Contributor Documentation (Coding Standards)

This document describes Javascript coding standards for Phabricator and Javelin.

Overview

This document outlines technical and style guidelines which are followed in Phabricator and Javelin. Contributors should also follow these guidelines. Many of these guidelines are automatically enforced by lint.

These guidelines are essentially identical to the Facebook guidelines, since I basically copy-pasted them. If you are already familiar with the Facebook guidelines, you can probably get away with skimming this document.

Spaces, Linebreaks and Indentation

• Use two spaces for indentation. Don't use literal tab characters.
• Use Unix linebreaks ("\n"), not MSDOS ("\r\n") or OS9 ("\r").
• Put a space after control keywords like if and for.
• Put a space after commas in argument lists.
• Put space around operators like =, <, etc.
• Don't put spaces after function names.
• Parentheses should hug their contents.
• Generally, prefer to wrap code at 80 columns.

Case and Capitalization

The Javascript language unambiguously dictates casing/naming rules; follow those rules.

• Name variables using lowercase_with_underscores.
• Name classes using UpperCamelCase.
• Name methods and properties using lowerCamelCase.
• Name global functions using lowerCamelCase. Avoid defining global functions.
• Name constants using UPPERCASE.
• Write true, false, and null in lowercase.
• "Internal" methods and properties should be prefixed with an underscore. For more information about what "internal" means, see Leading Underscores, below.

Comments

• Strongly prefer // comments for making comments inside the bodies of functions and methods (this lets someone easily comment out a block of code while debugging later).

Javascript Language

• Use [] and {}, not new Array and new Object.
• When creating an object literal, do not quote keys unless required.

Examples

if/else:

if (x > 3) {
  // ...
} else if (x === null) {
  // ...
} else {
  // ...
}

You should always put braces around the body of an if clause, even if it is only one line. Note that operators like > and === are also surrounded by spaces.

for (iteration):

for (var ii = 0; ii < 10; ii++) {
  // ...
}

Prefer ii, jj, kk, etc., as iterators, since they're easier to pick out visually and react better to "Find Next..." in editors.

for (enumeration):

for (var k in obj) {
  // ...
}

Make sure you use enumeration only on Objects, not on Arrays. For more details, see Javascript Object and Array.

switch:

switch (x) {
  case 1:
    // ...
    break;
  case 2:
    if (flag) {
      break;
    }
    break;
  default:
    // ...
    break;
}

break statements should be indented to block level. If you don't push them in, you end up with an inconsistent rule for conditional break statements, as in the 2 case.

If you insist on having a "fall through" case that does not end with break, make it clear in a comment that you wrote this intentionally. For instance:

switch (x) {
  case 1:
    // ...
    // Fall through...
  case 2:
    //...
    break;
}

Leading Underscores

By convention, methods names which start with a leading underscore are considered "internal", which (roughly) means "private". The critical difference is that this is treated as a signal to Javascript processing scripts that a symbol is safe to rename since it is not referenced outside the current file.

The upshot here is:

• name internal methods which shouldn't be called outside of a file's scope with a leading underscore; and
• never call an internal method from another file.

If you treat them as though they were "private", you won't run into problems.