JavaScript Coding Conventions

Introduction

This paper is a compilation of the above eight convention documents. It is not a substitute for those documents. It omits, for one, the authors' arguments supporting their positions. For example, Crockford writes, "All of our JavaScript code is sent directly to the public. It should always be of publication quality." That is reduced here to "Crockford: JavaScript should be publication quality."

Dojo has conventions that "must" be followed and "should" be followed. These are included here as conventions. It also has conventions that you "may" or "can" follow. These are not included here.

Each source is cited for each convention. If a convention is attributed to Amaran, Sakalos: the other documents do not cover this point or they disagree and are covered immediately, such as, "Crockford: Lines 80 characters wide. Nextapp: Lines 132 characters wide."

General

Crockford: JavaScript should be publication quality.

Murray: Use JavaScript conventions. (Links to Dojo conventions document.) Use OO JavaScript. XML is good but JSON can be better. Dereference unused objects. Use care with closures. Design for internationalization.

Komenda: Use library methods for cross-browser code.

Dojo: Violating conventions is OK if the violation improves readability.

File

Naming

Dojo: Use lowercase, one word.

Formatting

Crockford, Michaux, Dojo: Use blank lines to divide code into sections.

Michaux: Start sections with comment. Overall: namespace wrapper, then helper functions, constructors, private methods, mainline code, public methods, end namespace wrapper.

Sakalos: Start with JSDoc comment, then links to external library, namespace start, private variables, private functions, public functions, end namespace and end with eof comment.

Documenting

Other

Amaran: JavaScript inline w/HTML should be hidden from validator.

Objects

Arrays

Naming

Amaran: Prefix with underscore, if private, 'g' or 'm' for global or member, 'a' (for array) and name in UpperAndLower form.

Komenda, Dojo: Use plural for collections: for (person in people).

Other

Komenda: Use fast loop code: for (var i=0, len=arr.length; i < len; i++); Dojo: Variables initialized before loop are preferred over variables initialized in the loop.

Functions

Naming

Amaran: Use setAttr(), getAttr(), isAttr, doSomething.

Michaux: Use lowerAndUpper names.

Dojo: Use lowerAndUpper() for public methods. Use verb or verb phrase for methods ( getFish() ). Use get/set to access private fields. Use "is" prefix for boolean getter. UI widgets should be suffixed with type: leftComboBox.

Amaran, Dojo: Acronyms within names, only initial cap (getXml(), writeHtml() ).

Formatting

Murray: Function blocks not indented.

Documenting

Komenda: Include JSDoc comments with @param and @return comments. @param should list allowed types.

Other

Crockford, Komenda: Do not use new Function().

Komenda: Use var YDOM = YAHOO.util.Dom; to minimize function lookup time. Every function should only do one thing.

Other Objects

Naming

Crockford, Amaran: Use iniitial capital letter for objects that will be instantiated with new.

Dojo: Use UpperAndLower.

Crockford: Do not start with _. Dojo: Use _lowerAndUpper() for private methods.

Other

Murray: Use object hierarchies.

Blocks

Formatting

Amaran: Indent two or four spaces.

Michaux: Indent two spaces.

Crockford, Komenda, Dojo: Open curly at end of line above block; close curly on line below block, exdented.

        if (cond) {
            // statement[s]
        } else if {
            // statement[s]
        } else {
            // statement[s]
        }
        

Crockford, Nextapp: Always use blocks after if, for, etc.

Statements

Naming

Formatting

Dojo Sample broken line shows breaks before binary operators. [Editor's note: Dojo bases its conventions on the Geosoft Java conventions. Sun's Java conventions specify breaks before binary operators. Other Java conventions, including Geosoft's, specifically disagree with Sun on this point.]

Crockford, Nextapp, Amaran: Simple statements (including array/object assignments) end with ';'.

Crockford, Komenda: One statement per line.

Dojo: No space after break, catch, continue, do, else, finally, for, if, return, switch, this, try, void, while, with.
Space after case, default, delete, in, instanceof, new, throw, typeof, var.
Space after function if named; no space if anonymous.

Other

Crockford: The following table is from Crockford. Your editor added the try statement in a Crockford-like format. Comments in the table are also from Crockford.

            do {
                statements
            } while (condition);

            for (init; condition; update) {
                statements
            }

            for (x in y) {
                // if x.hasOwnProperty()
                statements
            }

            // always use blocks
            if (condition) {
                statements
            } else if (condition) {
                statements
            } else {
                statements
            }

            switch (expr) {
            case expression:
                statements
                break return or throw; // never fall through
            default:
                statements
            }

            try {
                statements
            } catch(ex) {
                statements
            } finally {
                statements
            }

            while (condition) {
                statements
            }

Expressions

Formatting

Dojo: Shows an example formatted this way:

        aVar = anObj.method(
                expr1,
                expr2,
                expr3
        );

Other

Crockford: Use === and !==, not == and !=. Use parens to separate binary and unary plus:foo + (+bar). Avoid the comma operator except for disciplined use in control part of for statements (comma operator, not comma list separator).

Komenda: Use object.property (not getAttribute(), setAttribute()) to access DOM object properties.

Dojo: Use temporary variables to avoid complex conditionals. if (normal case) {...} else (exceptional case) {...}. Use named constants, not numbers in code.

Variables

Naming

Crockford: Do not start with _. Dojo: Use _lowerAndUpper for private variables, method arguments and local variables.

Amaran: Two-letter prefix preceding UpperAndLower name. 'g' or 'm' (global or member), then sString, nNumber, bBoolean, aArray or oObject. gsHelloMsg = 'Hello, world!';. Prefix 'privates' with underscore.

Michaux: Use lowerAndUppercase.

Komenda: Use UPPER_CASE for global variables.

Dojo: Use lowerAndUpper for public variables. Use "num" prefix or "count" suffix as appropriate. Use "i", "j", ... for iterators. Complement names: get/set, add/remove, create/destroy, start/stop, insert/delete, begin/end, etc. Avoid abbreviations. No negated booleans: isNotFish is unacceptable. Use "Exception" and "Error" suffixes when appropriate.

        setFish(fish); // where fish's type = Fish

        getHandler(); // not getEventHandler();
        MouseEventHandler // not MsEvtHdlr
        events.mouse.Handler // not events.mouse.MouseEventHandler
        MouseEventHandler // extends EventHandler

Formatting

Crockford: Alphabetical order.

Documenting

Other

Crockford: Minimal globals. No implied globals.

Nextapp, Sakalos, Komenda, Michaux: All globals should be in namespaces. (Not in his convention, but Crockford codes this way.)

Dojo: Unless undefined is intended, assign a value when declaring variables. Never have dual meanings. Keep variables alive for the shortest time possible.

Constants

Naming

Formatting

            var TokenTypes = {
                    ResWord:1,
                    INTEGER:2
            }
            

Amaran: Single quotes for JavaScript literals, double quotes for HTML attribute values.

Komenda: Use single or double quotes, but be consistent.

Other

Comments

Nextapp: Use JSDoc comments for API specs.

Komenda: Use JSDoc comments for modules, functions. Mark browser workarounds with JSDoc HACK comments. Use JSDoc TODO comments when more should be done.

Dojo: Tricky code should be rewritten, not commented. Comments should be in English. Comments should precede or be to the right of the code they reference. Comments should identify the type of elements in a collection. Comments should precede blocks of code. Comments should not be included for every single line of code. [Editor: Dojo uses a comment system like that found in JSDoc, but it is not JSDoc.]