Greasemonkey - JavaScript Style Guide

This document describes the JavaScript style for the Greasemonkey project. Below, use of the word "should" is only for its effect on the prose, and actually means "must".

This guide is based on a Mozilla JavaScript Style Guide document which no longer exists (and was previously the Greasemonkey style guide), which in turn was based on a document by Niel Rashbrook.

Whitespace

• Indent blocks with two spaces. No tabs. Thus, blocks should be indented as:

  if (dlmgrWindow) {
    dlmgrWindow.focus();
  } else {
    dlmgr.open(window, null);
  }

• Lines should be no longer than 80 characters.
• When breaking statements across multiple lines, continuation lines should be indented by four spaces (not to align with something on the previous lines). For any "block" (function arguments, object literal contents, etc) the contents should all be on the following indented line, not following the opening brace. Or, bad:

  compMgr.registerFactoryLocation(CID,
                                  CLASSNAME,
                                  CONTRACTID,
                                  fileSpec,
                                  location,
                                  type);

  Bad:

  compMgr.registerFactoryLocation(CID, CLASSNAME, CONTRACTID, fileSpec,
      location, type);

  Good:

  compMgr.registerFactoryLocation(
      CID, CLASSNAME, CONTRACTID, fileSpec, location, type);

• Surround binary operators with single spaces.
• Put a single space after keywords (if, for, etc).
• Two blank lines between "top level" function/method definitions (those in the global scope, or in prototypes; not for locally scoped helper functions). Also consider breaking up distinct sections of code inside functions with blank lines.
• Files should contain exactly one newline at the end.
• Lines should have no trailing whitespace.

Symbols

• Spaces around braces used for in-line functions or objects, except before commas or semicolons, e.g.

  function valueObject(aValue) { return { value: aValue }; }

• Otherwise spaces are not necessary inside brackets.
• Prefer double quotes, except when quoting double quotes.
• Braces on if/else statements are not optional, unless the entire compound statement fits completely on one line.
• When continuing a single statement across a line, operators should be at the beginning of the continued line, including the dot (scope resolution). Examples:

  if (stack.filename != null
      && stack.filename != gmSvcFilename
      && stack.filename.substr(0, 6) != "chrome"
  ) {
    // ...
  }
  
  var loader = Cc["@mozilla.org/moz/jssubscript-loader;1"]
      .getService(Ci.mozIJSSubScriptLoader);

Code Style

• Always put else on its own line, as shown in the "Whitespace" section.
• Name inline functions, this makes it easier to debug them. Just assigning a function to a property doesn't name the function, you should to do something like:

  var offlineObserver = {
    observe: function OO_observe(aSubject, aTopic, aState) {
      if (aTopic == "network:offline-status-changed")
        setOfflineUI(aState == "offline");
    }
  };

  This helps with a number of editing and debugging tools.

Function and variable naming

• Unless otherwise specified, use camelCasedNames.
• Constants should be in UPPER_CASE.
• Use InterCaps and capitalize the first letter of constructors.
• Do not pollute the global namespace. Global (chrome window scoped) definitions should be avoided, but at least use a GM_ name prefix.
• Global state variables should be prefixed with the letter g, e.g. gFormatToolbar.
• Arguments (parameter names) should be prefixed with the letter a.
• Private members should start with _, e.g. _internalFunction. They should not be accessed except by the class they are a member of.
• Event handler functions should be prefixed with the word on, in particular try to use the names onLoad, onDialogAccept, onDialogCancel, etc., where this is unambiguous.
• Function names, local variables, and object members have no prefix.
• Try to declare local variables as near to their use as possible; initialize every variable.
• Only declare a variable once in each scope.

JavaScript Features

• Make sure that your code doesn't generate any strict JavaScript warnings, such as:
  • Duplicate variable declaration
  • Mixing return; with return value;
  • Trailing comma in JavaScript object declarations.
• Use [value1, value2] to create a JavaScript array in preference to using new Array(value1, value2).
• Use { member: value, ... } to create a JavaScript object; over new Object().
• Don't compare booleans to true or false. For example, write if (ioService.offline). Compare objects to null, numbers to 0 or strings to "" if there is chance for confusion.

Suggestions

These guidelines are not hard and fast rules, but almost always a good idea. Please try to follow them.

• Be very careful about assignments that are also used in a boolean context, e.g.

  while (node = node.parentNode) { /* ... */ }

  or

  for (var i=0, item; item=array[i]; i++) { /* ... */ }

  This can be a common source of subtle bugs.
• When a switch statement's case contains a body, and intentionally falls through to the next (with no break), add a comment like // fall-through to make it clear that this is intended.
• Don't use eval() or equivalents if there is any other possible way to accomplish the goal.
• Don't use setTimeout() or equivalents with string parameters, only function references. Generally avoid setTimeout() if at all possible — if not, comment why it was used.
• Keep branches, and especially commits, topically relevant. Don't put code refactoring and new features together in one commit, or even together in a branch if at all possible.