Web Development/Javascript Coding Standards

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.

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.