Web Development/Javascript Coding Standards

Revision as of 08:10, 16 June 2011

This document outlines technical and style guidelines which are followed in website-darenet. Contributors should also follow these guidelines.

Spaces, Linebreaks and Indentation

• Use one tab for each level of identation.
• Use Unix linebreaks ("\n"), not MSDOS ("\r\n") or OS9 ("\r").
• Use K&R style braces and spacing.
• 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.

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.