The first decision to be made about your JavaScript style guidelines (and indeed, about those of most languages) is how to handle indentation. This is one of those topics on which debates can last for hours; indentation is about as close to religion as software engineers get. However, it is quite important to establish indentation guidelines up front, lest developers fall into the classic problem of reindenting every file they open before starting to work. Consider a file that looks like this (indentation has been intentionally changed for demonstration purposes):

if (wl && wl.length) {
            for (i = 0, l = wl.length; i < l; ++i) {
         p = wl[i];
         type = Y.Lang.type(r[p]);
         if (s.hasOwnProperty(p)) { if (merge && type == 'object') {

    Y.mix(r[p], s[p]);
} else if (ov || !(p in r)) {
                    r[p] = s[p];
                }
            }
        }
    }

Just looking at this code quickly is difficult. The indentation isn’t uniform, so it appears that the else applies to the if statement on the first line. However, closer inspection reveals that the else actually applies to the if statement on line 5. The most likely culprit is a mixture of indentation styles from several different developers. This is precisely why indentation guidelines exist. Properly indented, this code becomes much easier to understand:

if (wl && wl.length) {
    for (i = 0, l = wl.length; i < l; ++i) {
        p = wl[i];
        type = Y.Lang.type(r[p]);
        if (s.hasOwnProperty(p)) {
            if (merge && type == 'object') {
                Y.mix(r[p], s[p]);
            } else if (ov || !(p in r)) {
                r[p] = s[p];
            }
        }
    }
}

Ensuring proper indentation is the first step—this particular piece of code has other maintainability issues discussed later in this chapter.

As with most style guidelines, there is no universal agreement on how to accomplish indentation in code. There are two schools of thought:

Though some may argue that one indentation approach or another is superior, it all boils down to a matter of preference within the team. For reference, here are some indentation guidelines from various style guides:

I recommend using four spaces per indentation level. Many text editors have this level as a default if you decide to make the Tab key insert spaces instead. I’ve found that two spaces don’t provide enough visual distinction for my eyes.

One of the interesting, and most confusing, aspects of JavaScript is that statements may be terminated either with a newline or with a semicolon. This breaks from the tradition of other C-like languages such as C++ and Java, which require semicolons. Both of the following examples are therefore valid JavaScript.

// Valid
var name = "Nicholas";
function sayName() {
    alert(name);
}

// Valid but not recommended
var name = "Nicholas"
function sayName() {
    alert(name)
}

The omission of semicolons works in JavaScript due to a mechanism known as automatic semicolon insertion (ASI). ASI looks for places in the code where a semicolon is appropriate and inserts one if not found. In many cases, ASI guesses correctly and there isn’t a problem. However, the rules of ASI are complex and difficult to remember, which is why I recommend using semicolons. Consider the following:

// Original Code
function getData() {
    return
    {
        title: "Maintainable JavaScript",
        author: "Nicholas C. Zakas"
    }
}

// The way the parser sees it
function getData() {
    return;
    {
        title: "Maintainable JavaScript",
        author: "Nicholas C. Zakas"
    };
}

In this example, the function getData() is intended to return an object containing some data. However, the newline after return causes a semicolon to be inserted, which causes the function to return undefined. The function can be fixed by moving the opening brace on to the same line as return.

// Works correctly, even without semicolons
function getData() {
    return {
        title: "Maintainable JavaScript",
        author: "Nicholas C. Zakas"
    }
}

There are scenarios where ASI may be applied, and I’ve found limiting ASI to help reduce errors. The errors are typically caused by misunderstanding how ASI works and assuming that a semicolon will be inserted when it will not. I have found that many developers, especially inexperienced ones, have an easier time using semicolons than omitting them.

Semicolon usage is recommended by Douglas Crockford’s Code Conventions for the JavaScript Programming Language (hereafter referred to as “Crockford’s Code Conventions”), the jQuery Core Style Guide, the Google JavaScript Style Guide, and the Dojo Style Guide. Both JSLint and JSHint will warn by default when semicolons are missing.

Closely related to the topic of indentation is line length. Developers find it hard to work on code in which the lines are long enough to require horizontal scrolling. Even with today’s large monitors, keeping line length reasonable greatly improves developer productivity. Code convention documents for many languages prescribe that lines of code should be no longer than 80 characters. This length comes from a time when text editors had a maximum of 80 columns in which to display text, so longer lines would either wrap in unexpected ways or disappear off the side of the editor. Today’s text editors are quite a bit more sophisticated than those of 20 years ago, yet 80-character lines are still quite popular. Here are some common line length recommendations:

Line length is less frequently found in JavaScript style guidelines, but Crockford’s Code Conventions specifies a line length of 80 characters. I also prefer to keep line length at 80 characters.

When a line reaches the maximum character length, it must be manually split into two lines. Line breaking is typically done after an operator, and the next line is indented two levels. For example (indents are four spaces):

// Good: Break after operator, following line indented two levels
callAFunction(document, element, window, "some string value", true, 123, 
        navigator);

// Bad: Following line indented only one level
callAFunction(document, element, window, "some string value", true, 123, 
    navigator);

// Bad: Break before operator
callAFunction(document, element, window, "some string value", true, 123
        , navigator);

In this example, the comma is an operator and so should come last on the preceding line. This placement is important because of ASI mechanism, which may close a statement at the end of a line in certain situations. By always ending with an operator, ASI won’t come into play and introduce possible errors.

The same line-breaking pattern should be used for statements as well:

if (isLeapYear && isFebruary && day == 29 && itsYourBirthday &&
        noPlans) {

    waitAnotherFourYears();
}

Here, the control condition of the if statement is split onto a second line after the && operator. Note that the body of the if statement is still indented only one level, allowing for easier reading.

There is one exception to this rule. When assigning a value to a variable, the wrapped line should appear immediately under the first part of the assignment. For example:

var result = something + anotherThing + yetAnotherThing + somethingElse +
             anotherSomethingElse;

This code aligns the variable anotherSomethingElse with something on the first line, ensuring readability and providing context for the wrapped line.

An often overlooked aspect of code style is the use of blank lines. In general, code should look like a series of paragraphs rather than one continuous blob of text. Blank lines should be used to separate related lines of code from unrelated lines of code. The example from the earlier section Indentation Levels is perfect for adding some extra blank lines to improve readability. Here’s the original:

if (wl && wl.length) {
    for (i = 0, l = wl.length; i < l; ++i) {
        p = wl[i];
        type = Y.Lang.type(r[p]);
        if (s.hasOwnProperty(p)) {
            if (merge && type == 'object') {
                Y.mix(r[p], s[p]);
            } else if (ov || !(p in r)) {
                r[p] = s[p];
            }
        }
    }
}

And here is the example rewritten with a few blank lines inserted:

if (wl && wl.length) {

    for (i = 0, l = wl.length; i < l; ++i) {
        p = wl[i];
        type = Y.Lang.type(r[p]);

        if (s.hasOwnProperty(p)) {

            if (merge && type == 'object') {
                Y.mix(r[p], s[p]);
            } else if (ov || !(p in r)) {
                r[p] = s[p];
            }
        }
    }
}

The guideline followed in this example is to add a blank line before each flow control statement, such as if and for. Doing so allows you to more easily read the statements. In general, it’s a good idea to also add blank lines:

None of the major style guides provide specific advice about blank lines, though Crockford’s Code Conventions does suggest using them judiciously.

Most of the code you write involves variables and functions, so determining naming conventions for those variables and functions is quite important to a comprehensive understanding of the code. JavaScript’s core, ECMAScript, is written using a convention called camel case. Camel-case names begin with a lowercase letter and each subsequent word begins with an uppercase letter. For example:

var thisIsMyName;
var anotherVariable;
var aVeryLongVariableName;

Generally speaking, you should always use a naming convention that follows the core language that you’re using, so camel case is the way most JavaScript developers name their variables and functions. The Google JavaScript Style Guide, the SproutCore Style Guide, and the Dojo Style Guide all specify use of camel case in most situations.

Even with the general naming convention of camel case in place, some more specific styles of naming are typically specified.

// Good
var count = 10;
var myName = "Nicholas";
var found = true;

// Bad: Easily confused with functions
var getCount = 10;
var isFound = true;

// Good
function getName() {
    return myName;
}

// Bad: Easily confused with variable
function theName() {
    return myName;
}

if (isEnabled()) {
    setName("Nicholas");
}

if (getName() === "Nicholas") {
    doSomething();
}

var MAX_COUNT = 10;
var URL = "http://www.nczonline.net/";

if (count < MAX_COUNT) {
    doSomething();
}

// Good
function Person(name) {
    this.name = name;
}

Person.prototype.sayName = function() {
    alert(this.name);
};

var me = new Person("Nicholas");

var me = Person("Nicholas");
var you = getPerson("Michael");

JavaScript has several types of primitive literal values: strings, numbers, booleans, null, and undefined. There are also object literals and array literals. Of these, only booleans are self-explanatory in their use. All of the other types require a little bit of thought as to how they should be used for optimum clarity.

// Valid JavaScript
var name = "Nicholas says, \"Hi.\"";

// Also valid JavaScript
var name = 'Nicholas says, "Hi"';

// Bad
var longString = "Here's the story, of a man \
named Brady.";

// Good
var longString = "Here's the story, of a man " +
                 "named Brady.";

// Integer
var count = 10;

// Decimal
var price = 10.0;
var price = 10.00;

// Bad Decimal: Hanging decimal point
var price = 10.;

// Bad Decimal: Leading decimal point
var price = .1;

// Bad: Octal (base 8) is deprecated
var num = 010;

// Hexadecimal (base 16)
var num = 0xA2;

// E-notation
var num = 1e23;

// Good
var person = null;

// Good
function getPerson() {
    if (condition) {
        return new Person("Nicholas");
    } else {
        return null;
    }
}

// Good
var person = getPerson();
if (person !== null) {
    doSomething();
}

// Bad: Testing against uninitialized variable
var person;
if (person != null) {
    doSomething();
}

// Bad: Testing to see whether an argument was passed
function doSomething(arg1, arg2, arg3, arg4) {
    if (arg4 != null) {
        doSomethingElse();
    }
}

// Bad
var person;
console.log(person === undefined);    //true

// foo is not declared
var person;
console.log(typeof person);     //"undefined"
console.log(typeof foo);        //"undefined"

// Good
var person = null;
console.log(person === null);    //true

// Bad
var book = new Object();
book.title = "Maintainable JavaScript";
book.author = "Nicholas C. Zakas";

// Good
var book = {
    title: "Maintainable JavaScript",
    author: "Nicholas C. Zakas"
};

// Bad
var colors = new Array("red", "green", "blue");
var numbers = new Array(1, 2, 3, 4);

// Good
var colors = [ "red", "green", "blue" ];
var numbers = [ 1, 2, 3, 4 ];

Single-line comments are created by using two slashes and end at the end of the line:

// Single-line comment

Many prefer to include a space after the two slashes to offset the comment text. There are three ways in which a single-line comment is used:

Single-line comments should not be used on consecutive lines unless you’re commenting out large portions of code. Multiline comments should be used when long comment text is required.

Here are some examples:

// Good
if (condition) {

    // if you made it here, then all security checks passed
    allowed();
}

// Bad: No empty line preceding comment
if (condition) {
    // if you made it here, then all security checks passed
    allowed();
}

// Bad: Wrong indentation
if (condition) {

// if you made it here, then all security checks passed
    allowed();
}

// Good
var result = something + somethingElse;    // somethingElse will never be null

// Bad: Not enough space between code and comment
var result = something + somethingElse;// somethingElse will never be null

// Good
// if (condition) {
//    doSomething();
//    thenDoSomethingElse();
// }

// Bad: This should be a multiline comment
// This next piece of code is quite difficult, so let me explain.
// What you want to do is determine whether the condition is true
// and only then allow the user in. The condition is calculated
// from several different functions and may change during the
// lifetime of the session.
if (condition) {
    // if you made it here, then all security checks passed
    allowed();
}

Multiline comments are capable of spanning multiple lines. They begin with /* and end with */. Multiline comments aren’t required to span multiple lines; that choice is up to you. The following are all valid multiline comments:

/* My comment */

/* Another comment.
This one goes to two lines. */

/*
Yet another comment.
Also goes to a second line.
*/

Although all of these comments are technically valid, I prefer the Java-style multiline comment pattern. The Java style is to have at least three lines: one for the /*, one or more lines beginning with a * that is aligned with the * on the previous line, and the last line for */. The resulting comment looks like this:

/*
 * Yet another comment.
 * Also goes to a second line.
 */

The result is a more legible comment that is visually aligned on the left to an asterisk. IDEs such as NetBeans and Eclipse will automatically insert these leading asterisks for you.

Multiline comments always come immediately before the code that they describe. As with single-line comments, multiline comments should be preceded by an empty line and should be at the same indentation level as the code being described. Here are some examples:

// Good
if (condition) {

    /*
     * if you made it here, 
     * then all security checks passed
     */
    allowed();
}

// Bad: No empty line preceding comment
if (condition) {
    /*
     * if you made it here, 
     * then all security checks passed
     */
    allowed();
}

// Bad: Missing a space after asterisk
if (condition) {

    /*
     *if you made it here, 
     *then all security checks passed
     */
    allowed();
}

// Bad: Wrong indentation
if (condition) {

/*
 * if you made it here, 
 * then all security checks passed
 */
    allowed();
}

// Bad: Don't use multiline comments for trailing comments
var result = something + somethingElse;    /*somethingElse will never be null*/

When to comment is a topic that always fosters great debate among developers. The general guidance is to comment when something is unclear and not to comment when something is apparent from the code itself. For example, the comment in this example doesn’t add any understanding to the code:

// Bad

// Initialize count
var count = 10;

It’s apparent from just the code that count is being initialized. The comment adds no value whatsoever. If, on the other hand, the value 10 has some special meaning that you couldn’t possibly know from looking at the code, then a comment would be very useful:

// Good

// Changing this value will make it rain frogs
var count = 10;

As implausible as it may be to make it rain frogs by changing the value of count, this is an example of a good comment, because it tells you something that you otherwise would be unaware of. Imagine how confused you would be if you changed the value and it started to rain frogs…all because a comment was missing.

So the general rule is to add comments where they clarify the code.

// Good

if (mode) {

    /*
     * In mode 2 (prototype to prototype and object to object), we recurse
     * once to do the proto to proto mix. The object to object mix will be
     * handled later on.
     */
    if (mode === 2) {
        Y.mix(receiver.prototype, supplier.prototype, overwrite,
                whitelist, 0, merge);
    }

    /*
     * Depending on which mode is specified, we may be copying from or to
     * the prototypes of the supplier and receiver.
     */
    from = mode === 1 || mode === 3 ? supplier.prototype : supplier;
    to   = mode === 1 || mode === 4 ? receiver.prototype : receiver;

    /*
     * If either the supplier or receiver doesn't actually have a
     * prototype property, then we could end up with an undefined from
     * or to. If that happens, we abort and return the receiver.
     */
    if (!from || !to) {
        return receiver;
    }
} else {
    from = supplier;
    to   = receiver;
}

while (element &&(element = element[axis])) { // NOTE: assignment
    if ( (all || element[TAG_NAME]) && 
       (!fn || fn(element)) ) {
            return element;
    }
}

var ret = false;

if ( !needle || !element || !needle[NODE_TYPE] || !element[NODE_TYPE]) {
    ret = false;
} else if (element[CONTAINS])  {
    // IE & SAF contains fail if needle not an ELEMENT_NODE 
    if (Y.UA.opera || needle[NODE_TYPE] === 1) { 
        ret = element[CONTAINS](needle);
    } else {
        ret = Y_DOM._bruteContains(element, needle); 
    }
} else if (element[COMPARE_DOCUMENT_POSITION]) { // gecko
    if (element === needle || !!(element[COMPARE_DOCUMENT_POSITION](needle) & 16)) { 
        ret = true;
    }
}

return ret;

Documentation comments aren’t technically part of JavaScript, but they are a very common practice. Document comments may take many forms, but the most popular is the form that matches JavaDoc documentation format: a multiline comment with an extra asterisk at the beginning (/**) followed by a description, followed by one or more attributes indicated by the @ sign. Here’s an example from YUI:

/**
Returns a new object containing all of the properties of all the supplied
objects. The properties from later objects will overwrite those in earlier
objects.

Passing in a single object will create a shallow copy of it. For a deep copy,
use `clone()`.

@method merge
@param {Object} objects* One or more objects to merge.
@return {Object} A new merged object.
**/
Y.merge = function () {
    var args   = arguments,
        i      = 0,
        len    = args.length,
        result = {};

    for (; i < len; ++i) {
        Y.mix(result, args[i], true);
    }

    return result;
};

The YUI library uses its own tool called YUIDoc to generate documentation from these comments. However, the format is almost exactly the same as the library-agnostic JSDoc Toolkit, which is widely used on open source projects as well as within Google. The key difference between YUIDoc and JSDoc Toolkit is that YUIDoc supports both HTML and Markdown in documentation comments, whereas JSDoc Toolkit supports only HTML.

It is highly recommended that you use a documentation generator with your JavaScript. The format of the comments must match the tool that you use, but the JavaDoc-style documentation comments are well supported across many documentation generators. When using documentation comments, you should be sure to document the following:

Of course, the exact comment format and how comments should be used will ultimately be determined by the documentation generator you choose.

A second topic related to block statements is the alignment of braces. There are two main styles of brace alignment. The first is to have the opening brace on the same line as the beginning of the block statement, as in this example:

if (condition) {
    doSomething();
} else {
    doSomethingElse();
}

JavaScript inherited this style from Java, where it is documented in the Code Conventions for the Java Programming Language. This style also now appears in Crockford’s Code Conventions, the jQuery Core Style Guide, the SproutCore Style Guide, the Google JavaScript Style Guide, and the Dojo Style Guide.

The second style of brace alignment places the opening brace on the line following the beginning of the block statement, as in this example:

if (condition)
{
    doSomething();
}
else
{
    doSomethingElse();
}

This style was made popular by C#, as Visual Studio enforces this alignment. There are no major JavaScript guides that recommend this style, and the Google JavaScript Style Guide explicitly forbids it due to fears of automatic semicolon insertion errors. My recommendation is to use the previous brace alignment format.

Spacing around the first line of a block statement is also a matter of preference. There are three primary styles for block statement spacing. The first is to have no spaces separating the statement name, the opening parenthesis, and the opening brace:

if(condition){
    doSomething();
}

This style is preferred by some programmers because it is more compact, though some complain that the compactness actually inhibits legibility. The Dojo Style Guide recommends this style.

The second style is to have a space separation before the opening parenthesis and after the closing parenthesis, such as:

if (condition) {
    doSomething();
}

Some programmers prefer this style because it makes the statement type and condition more legible. This is the style recommended by Crockford’s Code Conventions and the Google JavaScript Style Guide.

The third style adds spaces after the opening parenthesis and before the closing parenthesis, as in the following:

if ( condition ) {
    doSomething();
}

This is the style prescribed in the jQuery Core Style Guide, because it makes all aspects of the statement start quite clear and legible.

I prefer the second style as a nice compromise between the first and third styles.

Developers tend to have a love-hate relationship with the switch statement. There are varying ideas about how to use switch statements and how to format them. Some of this variance comes from the switch statement’s lineage, originating in C and making its way through Java into JavaScript without the exact same syntax.

Despite the similar syntax, JavaScript switch statements behave differently than in other languages: any type of value may be used in a switch statement, and any expression can be used as a valid case. Other languages require the use of primitive values and constants, respectively.

switch(condition) {
    case "first":
        // code
        break;

    case "second":
        // code
        break;

    case "third":
        // code
        break;

    default:
        // code
}

switch(condition) {    
case "first":
    // code
    break;        
case "second":
    // code
    break;        
case "third":
    // code
    break;    
default:
    // code
}

switch(condition) {

    // obvious fall through
    case "first":
    case "second":
        // code
        break;

    case "third":
        // code

        /*falls through*/        
    default:
        // code
}

switch(condition) {
    case "first":
        // code
        break;

    case "second":
        // code
        break;

    default:
        // do nothing
}

switch(condition) {
    case "first":
        // code
        break;

    case "second":
        // code
        break;

    // no default
}

The with statement changes how the containing context interprets variables. It allows properties and methods from a particular object to be accessed as if they were local variables and functions, omitting the object identifier altogether. The intent of with was to lessen the amount of typing developers need to do when using multiple object members in close proximity. For example:

var book = {
    title: "Maintainable JavaScript",
    author: "Nicholas C. Zakas"
};

var message = "The book is ";

with (book) {
    message += title;
    message += " by " + author;
}

In this code, the with statement is used to augment identifier resolution within the curly braces by allowing the properties of book to be accessed as if they were variables. The problem is that it’s hard to tell where title and author originated from. It’s not clear that these are properties of book and that message is a local variable. This confusion actually extends far beyond developers, with JavaScript engines and minifiers being forced to skip optimization of this section for fear of guessing incorrectly.

The with statement is actually disallowed in strict mode, causing a syntax error and indicating the ECMAScript committee’s belief that with should no longer be used. Crockford’s Code Conventions and the Google JavaScript Style Guide disallow the use of with. I strongly recommend avoiding the with statement, as it prevents you from easily applying strict mode to your code (a practice I recommend).

There are two types of for loops: the traditional for loop that JavaScript inherited from C and Java, as well as the for-in loop that iterates over properties for an object. These two loops, though similar, have two very different uses. The traditional for loop is typically used to iterate over members of an array, such as:

var values = [ 1, 2, 3, 4, 5, 6, 7 ],
    i, len;

for (i=0, len=values.length; i < len; i++) {
    process(values[i]);
}

There are two ways to modify how the loop proceeds (aside from using a return or throw statement). The first is to use the break statement. Using break causes the loop to exit immediately and not continue running even if the loop hasn’t finished all iterations. For example:

var values = [ 1, 2, 3, 4, 5, 6, 7 ],
    i, len;

for (i=0, len=values.length; i < len; i++) {
    if (i == 2) {
        break;  // no more iterations
    }
    process(values[i]);
}

The body of this loop will execute two times and then exit before executing process() the third time, even if the values array has more than three items.

The second way to modify how a loop proceeds is through the use of continue. The continue statement exits the loop immediately; however, the loop will continue with the next iteration. Here’s an example:

var values = [ 1, 2, 3, 4, 5, 6, 7 ],
    i, len;

for (i=0, len=values.length; i < len; i++) {
    if (i == 2) {
        continue;   // skip just this iteration
    }
    process(values[i]);
}

The body of this loop executes two times, skips the third time, and picks up with the fourth iteration. The loop will then continue until its last iteration unless otherwise interfered with.

Crockford’s Code Conventions disallows the use of continue. His assertion is that code using continue can better be written using conditions. For instance, the previous example can be rewritten as:

var values = [ 1, 2, 3, 4, 5, 6, 7 ],
    i, len;

for (i=0, len=values.length; i < len; i++) {
    if (i != 2) {           
        process(values[i]);
    }
}

Crockford argues that this pattern is easier for developers to understand and less error prone. The Dojo Style Guide states explicitly that continue, along with break, may be used. My recommendation is to avoid continue whenever possible, but there is no reason to completely forbid it. The readability of the code should dictate its usage.

JSLint warns when continue is used. JSHint does not warn when continue is used.

The for-in loop is used to iterate over properties of an object. Instead of defining a control condition, the loop systematically goes through each named object property and returns the property name inside of a variable, as in:

var prop;

for (prop in object) {
    console.log("Property name is " + prop);
    console.log("Property value is " + object[prop]);
}

A problem with for-in is that it returns not only instance properties of an object but also all properties it inherits through the prototype. You may thus end up with unanticipated results when iterating through properties on your own object. For this reason, it’s best to filter the for-in loop to only instance properties by using hasOwnProperty(). Here’s an example:

var prop;

for (prop in object) {
    if (object.hasOwnProperty(prop)) {
        console.log("Property name is " + prop);
        console.log("Property value is " + object[prop]);
    }
}

Crockford’s Code Conventions require the use of hasOwnProperty() for all for-in loops. Both JSLint and JSHint warn when a for-in loop is missing a call to hasOwnProperty() by default (both allow this option to be turned off). My recommendation is to always use hasOwnProperty() for for-in loops unless you’re intentionally looking up the prototype chain, in which case it should be indicated with a comment, such as:

var prop;

for (prop in object) {   // include prototype properties
    console.log("Property name is " + prop);
    console.log("Property value is " + object[prop]);
}

Another area of focus with for-in loops is their usage with objects. A common mistake is to use for-in to iterate over members of an array, as in this example:

// Bad
var values = [ 1, 2, 3, 4, 5, 6, 7],
    i;

for (i in values) {
    process(items[i]);
}

This practice is disallowed in Crockford’s Code Conventions as well as the Google JavaScript Style Guide due to the potential errors it may cause. Remember, the for-in is iterating over object keys on both the instance and the prototype, so it’s not limited to the numerically indexed properties of the array. The for-in loop should never be used in this way.

Variable declarations are accomplished by using the var statement. JavaScript allows the var statement to be used multiple times and nearly anywhere within a script. This usage creates interesting cognitive issues for developers, because all var statements are hoisted to the top of the containing function regardless of where they actually occur in the code. For example:

function doSomething() {

    var result = 10 + value;
    var value = 10;
    return result;
}

In this code, it’s perfectly valid for the variable value to be used before it was declared, though it will cause result to have the special value NaN. To understand why, you need to be aware that this code is changed by the JavaScript engine to this:

function doSomething() {

    var result;
    var value;

    result = 10 + value;
    value = 10;

    return result;
}

The two var statements are hoisted to the top of the function; the initialization happens afterward. The variable value has the special value undefined when it’s used on line 6, so result becomes NaN (not a number). Only after that is value finally assigned the value of 10.

One area where developers tend to miss variable declaration hoisting is with for statements, in which variables are declared as part of the initialization:

function doSomethingWithItems(items) {

    for (var i=0, len=items.length; i < len; i++) {
        doSomething(items[i]);
    }
}

JavaScript up to ECMAScript 5 has no concept of block-level variable declarations, so this code is actually equivalent to the following:

function doSomethingWithItems(items) {

    var i, len;

    for (i=0, len=items.length; i < len; i++) {
        doSomething(items[i]);
    }
}

Variable declaration hoisting means defining a variable anywhere in a function is the same as declaring it at the top of the function. Therefore, a popular style is to have all variables declared at the top of a function instead of scattered throughout. In short, you end up writing code similar to the manner in which the JavaScript engine will interpret it.

My recommendation is to have your local variables defined as the first statements in a function. This approach is recommended in Crockford’s Code Conventions, the SproutCore Style Guide, and the Dojo Style Guide:

function doSomethingWithItems(items) {

    var i, len;
    var value = 10;
    var result = value + 10;

    for (i=0, len=items.length; i < len; i++) {
        doSomething(items[i]);
    }
}

Crockford goes on to recommend the use of a single var statement at the top of functions:

function doSomethingWithItems(items) {

    var i, len,
        value = 10,
        result = value + 10;

    for (i=0, len=items.length; i < len; i++) {
        doSomething(items[i]);
    }
}

The Dojo Style Guide allows combining var statements only when the variables are related to one another.

My personal preference is to combine all var statements with one initialized variable per line. The equals signs should be aligned. For variables that aren’t initialized, they should appear last, as in the following example:

function doSomethingWithItems(items) {

    var value   = 10,
        result  = value + 10,
        i, 
        len;

    for (i=0, len=items.length; i < len; i++) {
        doSomething(items[i]);
    }
}

At a minimum, I recommend combining var statements, as doing so makes your code smaller and therefore faster to download.

Function declarations, just like variable declarations, are hoisted by JavaScript engines. Therefore, it’s possible to use a function in code before it is declared:

// Bad
doSomething();

function doSomething() {
    alert("Hello world!");
}

This approach works because the JavaScript engine interprets the code as if it were the following:

function doSomething() {
    alert("Hello world!");
}

doSomething();

Due to this behavior, it’s recommended that JavaScript functions always be declared before being used. This design appears in Crockford’s Code Conventions. Crockford also recommends that local functions be placed immediately after variable declarations within a containing function, as in:

function doSomethingWithItems(items) {

    var i, len,
        value = 10,
        result = value + 10;

    function doSomething(item) {
        // do something
    }

    for (i=0, len=items.length; i < len; i++) {
        doSomething(items[i]);
    }
}

Both JSLint and JSHint will warn when a function is used before it is declared.

Additionally, function declarations should never appear inside of block statements. For example, this code won’t behave as expected:

// Bad
if (condition) {
    function doSomething() {
        alert("Hi!");
    }
} else {
    function doSomething() {
        alert("Yo!");
    }
}

Exactly how this will work from browser to browser will vary. Most browsers automatically take the second declaration without evaluating condition; Firefox evaluates condition and uses the appropriate function declaration. This is a gray area in the ECMAScript specification and should thus be avoided. Function declarations should be used only outside of conditional statements. This pattern is explicitly forbidden in the Google JavaScript Style Guide.

Almost universally, the recommended style for function calls is to have no space between the function name and the opening parenthesis, which is done to differentiate it from a block statement. For example:

// Good
doSomething(item);

// Bad: Looks like a block statement
doSomething (item);

// Block statement for comparison
while (item) {
    // do something
}

Crockford’s Code Conventions explicitly calls this out. The Dojo Style Guide, SproutCore Style Guide, and Google JavaScript Style Guide implicitly recommend this style through code examples.

The jQuery Core Style Guide further specifies that an extra space should be included after the opening parenthesis and before the closing parenthesis, such as:

// jQuery-style
doSomething( item );

The intent here is to make the arguments easier to read. The jQuery Core Style Guide also lists some exceptions to this style, specifically relating to functions that are passed a single argument that is an object literal, array literal, function expression, or string. So the following examples are all still considered valid:

// jQuery exceptions
doSomething(function() {});
doSomething({ item: item });
doSomething([ item ]);
doSomething("Hi!");

Generally speaking, styles with more than one exception are not good, because they can be confusing to developers.

JavaScript allows you to declare anonymous functions—functions without proper names—and assign those functions to variables or properties. For example:

var doSomething = function() {
    // function body
};

Such anonymous functions can also be immediately invoked to return a value to the variable by including parentheses at the very end:

// Bad
var value = function() {

    // function body

    return {
        message: "Hi"
    }
}();

In the previous example, value ends up being assigned an object, because the function is immediately invoked. The problem with this pattern is that it looks very similar to assigning an anonymous function to a variable. You don’t know that this isn’t the case until you get to the very last line and see the parentheses. This sort of confusion hinders the readability of your code.

To make it obvious that immediate function invocation is taking place, put parentheses around the function, as in this example:

// Good
var value = (function() {

    // function body

    return {
        message: "Hi"
    }
}());

This code now has a signal on the first line, the open paren, that the function is immediately invoked. Adding the parentheses doesn’t change the behavior of the code at all. Crockford’s Code Conventions recommends this pattern, and JSLint will warn when the parentheses are missing.

"use strict";

// Bad - global strict mode
"use strict";

function doSomething() {
    // code
}

// Good
function doSomething() {
    "use strict";

    // code
}

// Good
(function() {
    "use strict";

    function doSomething() {
        // code
    }

    function doSomethingElse() {
        // code
    }    

})();

Equality in JavaScript is tricky due to type coercion. Type coercion causes variables of a specific type to be converted automatically into a different type for a particular operation to succeed, which can lead to some unexpected results.

One of the main areas in which type coercion occurs is with the use of equality operators, == and !=. These two operators cause type coercion when the two values being compared are not the same data type (when they are the same data type, no coercion occurs). There are many instances in which code may not be doing what you expect.

If you compare a number to a string, the string is first converted to a number, and then the comparison happens. Some examples:

// The number 5 and string 5
console.log(5 == "5");          // true

// The number 25 and hexadecimal string 25
console.log(25 == "0x19");      // true

When performing type coercion, the string is converted to a number as if using the Number() casting function. Because Number() understands hexadecimal format, it will convert a string that looks like a hexadecimal number into the decimal equivalent before the comparison occurs.

If a boolean value is compared to a number, then the boolean is converted to a number before comparison. A false value becomes 0 and true becomes 1. For example:

// The number 1 and true
console.log(1 == true);     // true

// The number 0 and false
console.log(0 == false);    // true

// The number 2 and true
console.log(2 == true);     // false

If one of the values is an object and the other is not, then the object’s valueOf() method is called to get a primitive value to compare against. If valueOf() is not defined, then toString() is called instead. After that point, the comparison continues following the previously discussed rules about mixed type comparisons. For example:

var object = {
    toString: function() {
        return "0x19";
    }
};

console.log(object == 25);      // true

The object is deemed to be equal to the number 25 because its toString() method returned the hexadecimal string "0x19", which was then converted to a number before being compared to 25.

The last instance of type coercion occurs between null and undefined. These two special values are deemed to be equivalent simply by the letter of the ECMAScript standard:

console.log(null == undefined);     // true

Because of type coercion, avoiding == and != at all is recommended; instead, use === and !==. These operators perform comparison without type coercion. So if two values don’t have the same data type, they are automatically considered to be unequal, which allows your comparison statements to always perform the comparison in a way that is more consistent. Consider the differences between == and === in a few cases:

// The number 5 and string 5
console.log(5 == "5");          // true
console.log(5 === "5");         // false

// The number 25 and hexadecimal string 25
console.log(25 == "0x19");      // true
console.log(25 === "0x19");     // false

// The number 1 and true
console.log(1 == true);         // true
console.log(1 === true);        // false

// The number 0 and false
console.log(0 == false);        // true
console.log(0 === false);       // false

// The number 2 and true
console.log(2 == true);         // false    
console.log(2 === true);        // false

var object = {
    toString: function() {
        return "0x19";
    }
};

// An object and 25
console.log(object == 25);      // true
console.log(object === 25);     // false

// Null and undefined
console.log(null == undefined); // true
console.log(null === undefined);// false

Use of === and !== is recommended by Crockford’s Code Conventions, the jQuery Core Style Guide, and the SproutCore Style Guide. Crockford’s guide recommends usage all the time, but specifically for comparing against false values (those values that are coerced to false, such as 0, the empty string, null, and undefined). The jQuery Core Style Guide allows the use of == for comparison against null when the intent is to test for both null and undefined. I recommend using === and !== all the time without exception.

JSLint warns about all uses of == and != by default. JSHint warns about using == and != when comparing to a false value by default. You can enable warnings for all uses of == and != by adding the eqeqeq option.

The eval() function takes a string of JavaScript code and executes it. This function allows developers to download additional JavaScript code, or to generate JavaScript code on the fly, and then execute it. For example:

eval("alert('Hi!')");

var count = 10;
var number = eval("5 + count");
console.log(number);     // 15

The eval() function isn’t the only way to execute a JavaScript string from within JavaScript. The same can be done using the Function constructor as well as setTimeout() and setInterval(). Here are some examples:

var myfunc = new Function("alert('Hi!')");

setTimeout("document.body.style.background='red'", 50);

setInterval("document.title = 'It is now '" + (new Date()), 1000);

All of these are considered bad practice by most of the JavaScript community. Although eval() may be used from time to time in JavaScript libraries (mostly in relation to JSON), the other three uses are rarely, if ever, used. A good general guideline is to never use Function and to use eval() only if no other options are present. Both setTimeout() and setInterval() can be used but should use function instead of strings:

setTimeout(function() {
    document.body.style.background='red';
}, 50);

setInterval(function() {
    document.title = 'It is now ' + (new Date());
}, 1000);

Crockford’s Code Conventions forbids the use of eval() and Function, as well as setTimeout() and setInterval() when used with strings. The jQuery Core Style Guide forbids the use of eval() except for a JSON parsing fallback used in one place. The Google JavaScript Style Guide allows the use of eval() only for converting Ajax responses into JavaScript values.

Both JSLint and JSHint warn about the use of eval(), Function, setTimeout(), and setInterval() by default.

A little-known and often misunderstood aspect of JavaScript is the language’s reliance on primitive wrapper types. There are three primitive wrapper types: String, Boolean, and Number. Each of these types exists as a constructor in the global scope and each represents the object form of its respective primitive type. The main use of primitive wrapper types is to make primitive values act like objects, for instance:

var name = "Nicholas";
console.log(name.toUpperCase());

Even though name is a string, which is a primitive type and therefore not an object, you’re still able to use methods such as toUpperCase() as if the string were an object. This usage is made possible because the JavaScript engine creates a new instance of the String type behind the scenes for just that statement. Afterward, it’s destroyed, and another is created when it is needed. You can test out this behavior by trying to add a property to a string:

var name = "Nicholas";
name.author = true;
console.log(name.author);   // undefined

The author property has vanished after the second line. That’s because the temporary String object representing the string was destroyed after line 2 executed, and a new String object was created for line 3. It’s possible to create these objects yourself as well:

// Bad
var name = new String("Nicholas");
var author = new Boolean(true);
var count = new Number(10);

Although it’s possible to use these primitive wrapper types, I strongly recommend avoiding them. Developers tend to get confused as to whether they’re dealing with an object or a primitive, and bugs occur. There isn’t any reason to create these objects yourself.

The Google JavaScript Style Guide forbids the use of primitive wrapper types. Both JSLint and JSHint will warn if you try to use String, Number, or Boolean to create new objects.

Many design patterns are actually solutions to the problem of tight coupling. If two components are tightly coupled, it means that one component has direct knowledge of the other in such a way that a change to one of the components often necessitates a change to the other component. For example, suppose you have a CSS class named error that is used throughout a website, embedded in HTML. If one day you decide that error isn’t the right name for the class and you want to change it to warning, you’ll have to edit not just the CSS but also all of the HTML using that class. The HTML is tightly coupled to the CSS. This is just a simple example. Imagine what a nightmare it is when a system has dozens or hundreds of components.

Loose coupling is achieved when you’re able to make changes to a single component without making changes to other components. Loose coupling is essential to the maintainability of large systems for which more than one person is responsible for the development and maintenance of code. You absolutely want developers to be able to make changes in one area of the code without breaking what other developers are doing in a different area of code.

Loose coupling is achieved by limiting each component’s knowledge of the larger system. In essence, every component needs to be as dumb as possible to ensure loose coupling. The less a component knows, the better off the entire system tends to be.

One thing to keep in mind: there is no such thing as no coupling between components that work together. In any system, there will necessarily be some knowledge shared between components in order to do their job. That’s okay. The goal is to ensure that changes in one component don’t require changes in multiple places on a regular basis.

A web UI that is loosely coupled is easier to debug. Issues with text or structure are addressed by looking just at HTML. When stylistic issues arise, you know the problem and the fix will be in the CSS. Finally, if there are behavioral issues, you can go straight to the JavaScript to address the problem. This ability is a key part of a maintainable web interface.

There was a feature in Internet Explorer 8 and earlier that some loved and many hated: CSS expressions. CSS expressions allow you to insert JavaScript directly into CSS, performing calculations or other functionality directly inside CSS code. For example, the following code sets the width of an element to match the width of the browser:

/* Bad */
.box {
    width: expression(document.body.offsetWidth + "px");
}

The CSS expression is enclosed in the special expression() function, which accepts any JavaScript code. CSS expressions are reevaluated frequently by the browser and were considered to be bad for performance, even making it into Steve Souders’s book High Performance Web Sites as something to avoid (Rule 7: Avoid CSS Expressions).

Aside from the performance issues, having JavaScript embedded inside of CSS is a maintenance nightmare, and one with which I have firsthand experience. In 2005, I had a JavaScript bug assigned to me that had me baffled from the start. It occurred only in Internet Explorer and happened only when the browser window was resized a few times. At that point in time, the best JavaScript debugger for Internet Explorer was Visual Studio, but it failed to locate the source of the problem. I spent an entire day setting breakpoints and inserting alert() statements to try to figure out what was happening.

By the end of the day, I had resigned myself to my least favorite debugging method: systematic removal of code. I removed JavaScript, file by file, and tried to reproduce the issue. I quickly became frustrated and simply removed all JavaScript from the page. The bug was still happening. I look at my computer screen in disbelief. A JavaScript error without any JavaScript on the page—how is that even possible?

To this day, I’m still not sure what led me finally to look at the CSS. I wasn’t even sure what I was looking for at that point. I just started at the top of the CSS and slowly scrolled down to see if anything would jump out at me. Finally, I saw the CSS expression that was the source of the problem. When I removed it, the JavaScript error went away.

This experience is what led me to the rules in this chapter. I spent an entire day looking for a JavaScript bug in JavaScript when it was actually in CSS. The actual error wasn’t even difficult to solve, but tracking down the error in a part of the system in which I (reasonably) didn’t expect to find it was ridiculously time consuming.

Fortunately, Internet Explorer 9 removed support for CSS expressions, but older versions of Internet Explorer are still in use around the world. Even though it’s tempting to use a CSS expression to make up for some of the missing functionality in these older browsers, resist the urge and save yourself a lot of time and effort. Keep JavaScript out of your CSS.

Keeping this clean separation between CSS and JavaScript can be challenging at times. These two languages work quite well together, so it is tempting to manipulate style data within JavaScript. The most popular way to script style changes is through the use of the style property on any DOM element. The style property is an object containing properties that allow you to read and change CSS properties. For instance, you can change the text color of an element to red like this:

// Bad
element.style.color = "red";

It’s actually quite common to see large blocks of code using style to change multiple properties, such as:

// Bad
element.style.color = "red";
element.style.left = "10px";
element.style.top = "100px";
element.style.visibility = "visible";

This approach is problematic, because the style information is now located inside of JavaScript instead of CSS. When there is a style problem, you should be able to go straight to the CSS to find and resolve the issue. You wouldn’t stop to consider that the style information is in JavaScript until you’d exhausted all other possibilities.

Another way developers use the style object is to set an entire CSS string via the cssText property, as in the following example:

// Bad
element.style.cssText = "color: red; left: 10px; top: 100px; visibility: hidden";

Using the cssText property is just a shortcut to set multiple CSS properties at once. This pattern has the same problem as setting individual properties: keeping style information inside of your JavaScript is a maintenance problem.

Keeping CSS out of JavaScript means that all style information still lives in CSS. When JavaScript needs to change the style of an element, the best way to do so is by manipulating CSS classes. For instance, to reveal a dialog box on the page, define a class in your CSS such as this:

.reveal {
    color: red;
    left: 10px;
    top: 100px;
    visibility: visible;
}

Then, in JavaScript, add the class to the element in question:

// Good - Native
element.className += " reveal";

// Good - HTML5
element.classList.add("reveal");

// Good - YUI
Y.one(element).addClass("reveal");

// Good - jQuery
$(element).addClass("reveal");

// Good - Dojo
dojo.addClass(element, "reveal");

Think of CSS class names as the communication mechanism between CSS and JavaScript. JavaScript is free to add and remove class names from elements throughout the life cycle of the page. The styles applied by the classes are defined in the CSS code. Those styles may change at any point in time in the CSS without necessitating a JavaScript update. JavaScript should not be manipulating styles directly so that it stays loosely coupled to the CSS.

One of the first things people do when they learn JavaScript is start embedding it within HTML. There are any number of ways to do this. The first is to assign event handlers by using the on attributes such as onclick:

<!-- Bad -->
<button onclick="doSomething()" id="action-btn">Click Me</button>

This is how most websites with JavaScript were coded around the year 2000. HTML was littered with onclick and other event handlers as attributes of elements. Although this code will work in most situations, it represents tight coupling of two UI layers (HTML and JavaScript), so there are several problems with it.

First, the doSomething() function must be available when the button is clicked. Those who developed websites around 2000 are quite familiar with this problem. The code for doSomething() may be loaded from an external file or may occur later in the HTML file. Either way, it’s possible for a user to click the button before the function is available and cause a JavaScript error. The resulting error message may pop up to the user or cause the button to appear to do nothing. Either case is undesirable.

The second problem is a maintenance issue. What happens if you want to change the name of doSomething()? What happens if the button should now call a different function when clicked? In both cases, you’re making changes to both the JavaScript and the HTML; this is the very essence of tightly coupled code.

Most—if not all—of your JavaScript should be contained in external files and included on the page via a <script> element. The on attributes should not be used for attaching event handlers in HTML. Instead, use JavaScript methods for adding event handlers once the external script has been loaded. For DOM Level 2–compliant browsers, you can achieve the same behavior in the previous example by using this code:

function doSomething() {
    // code
}

var btn = document.getElementById("action-btn");
btn.addEventListener("click", doSomething, false);

The advantage of this approach is that the function doSomething() is defined in the same file as the code that attatches the event handler. If the function name needs to change, there is just one file that needs editing; if the button should do something else when clicked, there is still just one place to go to make that change.

Internet Explorer 8 and earlier versions don’t support addEventListener(), so you may need a function to normalize the difference:

function addListener(target, type, handler) {
    if (target.addEventListener) {
        target.addEventListener(type, handler, false);
    } else if (target.attachEvent) {
        target.attachEvent("on" + type, handler);
    } else {
        target["on" + type] = handler;
    }
}

This function is capable of adding an event handler for an element in any browser, even falling back to the DOM Level 0 approach of assigning a handler to the on property of an object (this step would be necessary only for very old browsers such as Netscape 4, but it’s always good to cover your bases). This method is used as follows:

function doSomething() {
    // code
}

var btn = document.getElementById("action-btn");
addListener(btn, "click", doSomething);

If you’re using a JavaScript library, you should use the library’s methods for adding an event handler to an element. Here are some common examples for popular libraries:

// YUI
Y.one("#action-btn").on("click", doSomething);

// jQuery
$("#action-btn").on("click", doSomething);

// Dojo
var btn = dojo.byId("action-btn");
dojo.connect(btn, "click", doSomething);

Another way of embedding JavaScript in HTML is to use the <script> element with inline code:

<!-- Bad -->
<script>       
    doSomething();
</script>

It’s best to keep all JavaScript in external files and to keep inline JavaScript code out of your HTML. Part of the reason for this approach is to aid in debugging. When a JavaScript error occurs, your first inclination is to start digging through your JavaScript files to find the issue. If the JavaScript is located in the HTML, that’s a workflow interruption. You first have to determine whether the JavaScript is in the JavaScript files (which it should be) or in the HTML. Only then can you start debugging.

This point might seem minor, especially given today’s excellent web development tools, but it is actually an important piece of the maintenance puzzle. Predictability leads to faster debugging and development, and knowing (not guessing) where to start with a bug is what leads to faster resolutions and better overall code quality.

Just as it’s best to keep JavaScript out of HTML, it’s also best to keep HTML out of JavaScript. As mentioned previously, when there is a text or structural issue to debug, you want to be able to go to the HTML to start debugging. Many times in my career I’ve had trouble tracking down such an issue because I was looking at the HTML when in fact the real issue was buried deep inside JavaScript.

HTML frequently ends up in JavaScript as a consequence of using the innerHTML property, as in:

// Bad
var div = document.getElementById("my-div");
div.innerHTML = "<h3>Error</h3><p>Invalid e-mail address.</p>";

Embedding HTML strings inside your JavaScript is a bad practice for a number of reasons. First, as mentioned previously, it complicates tracking down text and structural issues. The typical approach for debugging perceived markup issues is to first look at the DOM tree in the browser’s inspector, then look at the HTML source of the page to find differences. Tracking down these issues becomes more problematic when JavaScript is doing more than simple DOM manipulation.

The second problem with this approach is maintainability. If you need to change text or markup, you want to be able to go to one place: the place where you manage HTML. This may be in PHP code, a JSP file, or even a template such as Mustache or Handlebars. Regardless of the mechanism used, you want all of your markup to be in one location so that it can be easily updated. Markup embedded within JavaScript isn’t as accessible for changes, because it’s unexpected. Why would you think to go into your JavaScript to make a markup change when most of the markup is located inside of a directory of template files?

It’s far less error prone to edit markup than it is to edit JavaScript. By placing HTML into JavaScript, you’ve complicated the problem. JavaScript strings require proper escaping of quote characters, meaning that the markup needs slightly different syntax than it would in templates.

Because most web applications are quite dynamic in nature and JavaScript is often used to change the UI during the life cycle of the page, it is definitely necessary to use JavaScript to insert or otherwise manipulate markup on the page. There are several ways to accomplish this in a loosely coupled manner.

function loadDialog(name, oncomplete) {

    var xhr = new XMLHttpRequest();
    xhr.open("get", "/js/dialog/" + name, true);

    xhr.onreadystatechange = function() {

        if (xhr.readyState == 4 && xhr.status == 200) {

            var div = document.getElementById("dlg-holder");
            div.innerHTML = xhr.responseText;
            oncomplete();

        } else {
            // handle error
        }
    };

    xhr.send(null);
}

// YUI
function loadDialog(name, oncomplete) {
    Y.one("#dlg-holder").load("/js/dialog/" + name, oncomplete);
}

// jQuery
function loadDialog(name, oncomplete) {
    $("#dlg-holder").load("/js/dialog/" + name, oncomplete);
}

<li><a href="%s">%s</a></li>

function sprintf(text) {
    var i=1, args=arguments;
    return text.replace(/%s/g, function() {
        return (i < args.length) ? args[i++] : "";
    });
}

// usage
var result = sprintf(templateText, "/item/4", "Fourth item");

<ul id="mylist"><!--<li id="item%s"><a href="%s">%s</a></li>-->
    <li><a href="/item/1">First item</a></li>
    <li><a href="/item/2">Second item</a></li>
    <li><a href="/item/3">Third item</a></li>
</ul>

var mylist          = document.getElementById("mylist"),
    templateText    = mylist.firstChild.nodeValue;

function addItem(url, text) {
    var mylist          = document.getElementById("mylist"),
        templateText    = mylist.firstChild.nodeValue,
        result          = sprintf(templateText, url, text);

    mylist.insertAdjacentHTML("beforeend", result);
}

// usage
addItem("/item/4", "Fourth item");

<script type="text/x-my-template" id="list-item">
    <li><a href="%s">%s</a></li>
</script>

var script          = document.getElementById("list-item"),
    templateText    = script.text;

function addItem(url, text) {
    var mylist          = document.getElementById("mylist"),
        script          = document.getElementById("list-item"),
        templateText    = script.text,
        result          = sprintf(templateText, url, text),
        div             = document.createElement("div");

    div.innerHTML = result.replace(/^\s*/, "");
    mylist.appendChild(div.firstChild);
}

// usage
addItem("/item/4", "Fourth item");

<li><a href="{{url}}">{{text}}</a></li>

<script type="text/x-handlebars-template" id="list-item">
    <li><a href="{{url}}">{{text}}</a></li>
</script>

var script          = document.getElementById("list-item"),
    templateText    = script.text,
    template        = Handlebars.compile(script.text);

var result = template({ 
    text: "Fourth item", 
    url: "/item/4"
});

function addItem(url, text) {
    var mylist          = document.getElementById("mylist"),
        script          = document.getElementById("list-item"),
        templateText    = script.text,
        template        = Handlebars.compile(script.text),
        div             = document.createElement("div"),
        result;

    result = template({ 
        text: text,
        url: url
    });

    div.innerHTML = result;
    list.appendChild(div.firstChild);
}

// usage
addItem("/item/4", "Fourth item");

{{#if items}}
<ul>
    {{#each items}}
    <li><a href="{{url}}">{{text}}</a></li>
    {{/each}}
</ul>
{{/if}

// return an empty string
var result = template({
    items: []
});

// return HTML for a list with two items
var result = template({
    items: [
        {
            text: "First item", 
            url: "/item/1"
        },
        {
            text: "Second item", 
            url: "/item/2"
        }
    ]
});

Creating globals is considered a bad practice in general and is specifically problematic in a team development environment. Globals create a number of nontrivial maintenance issues for code going forward. The more globals, the greater the possibility that errors will be introduced due to the increasing likelihood of a few common problems.

function sayColor() {
    alert(color);       // Bad: where'd this come from?
}

function sayColor(color) {
    alert(color);
}

One of the more insidious parts of JavaScript is its capacity for creating globals accidentally. When you assign a value to variable that has not previously been defined in a var statement, JavaScript automatically creates a global variable. For example:

function doSomething() {
    var count = 10;
        title = "Maintainable JavaScript";  // Bad: global

}

This code represents a very common coding error that accidentally introduces a global variable. The author probably wanted to declare two variables using a single var statement but accidentally included a semicolon after the first variable instead of a comma. The result is the creation of title as a global variable.

The problem is compounded when you’re trying to create a local variable with the same name as a global variable. For example, a global variable named count would be shadowed by the local variable count in the previous example. The function then has access only to the local count unless explicitly accessing the global using window.count. This arrangement is actually okay.

Omitting the var statement accidentally might mean that you’re changing the value of an existing global variable without knowing it. Consider the following:

function doSomething() {
    var count = 10;
        name = "Nicholas";  // Bad: global

}

In this example, the error is even more egregious because name is actually a property of window by default. When the window.name property is most frequently used with frames or iframes, and is how links are targeted to show up in certain frames or tabs when clicked, changing name inadvertently could affect how links navigate in the site.

A good rule of thumb is to always use var to define variables, even if they are global. This way is a lot less error prone than omitting the var in certain situations.

foo = 10;

"use strict";
foo = 10;           // ReferenceError: foo is not defined

You may be thinking at this point, “How is it possible to write JavaScript without introducing any globals?” Although it is technically possible through some clever patterns, this approach is usually not feasible or maintainable in the long run. When JavaScript is developed by a team, that typically means that multiple files are loaded in various scenarios, and the only way to enable communication between this disparate code is to have something that all of the code can rely on to be present. The best approach is to try to have as small a global footprint as possible by agreeing to create only one global object.

The one-global approach is used by all popular JavaScript libraries:

The idea behind the one-global approach is to create a single global with a unique name (one that is unlikely to be used by native APIs) and then attach all of your functionality onto that one global. So instead of creating multiple globals, each would-be global simply becomes a property of your one global. For instance, suppose I wanted to have an object representing each chapter in this book. The code might look like this:

function Book(title) {
    this.title = title;
    this.page = 1;
}

Book.prototype.turnPage = function(direction) {
    this.page += direction;
};

var Chapter1 = new Book("Introduction to Style Guidelines");
var Chapter2 = new Book("Basic Formatting");
var Chapter3 = new Book("Comments");

This code creates four globals, Book, Chapter1, Chapter2, and Chapter3. The one-global approach would be to create a single global and attach each of these:

var MaintainableJS = {};

MaintainableJS.Book = function(title) {
    this.title = title;
    this.page = 1;
};

MaintainableJS.Book.prototype.turnPage = function(direction) {
    this.page += direction;
};

MaintainableJS.Chapter1 = new MaintainableJS.Book("Introduction to Style Guidelines");
MaintainableJS.Chapter2 = new MaintainableJS.Book("Basic Formatting");
MaintainableJS.Chapter3 = new MaintainableJS.Book("Comments");

This code has a single global, MaintainableJS, to which all of the other information is attached. As long as everyone on the team is aware of the single global, it’s easy to continue adding properties to it and avoid global pollution.

var ZakasBooks = {};

// namespace for this book
ZakasBooks.MaintainableJavaScript = {};

// namespace for another book
ZakasBooks.HighPerformanceJavaScript = {}

var YourGlobal = {
    namespace: function(ns) {
        var parts = ns.split("."),
            object = this,
            i, len;

        for (i=0, len=parts.length; i < len; i++) {
            if (typeof object[parts[i]] === "undefined") {
                object[parts[i]] = {};
            }
            object = object[parts[i]];
        }

        return object;
    }
};

/*
 * Creates both YourGlobal.Books and YourGlobal.Books.MaintainableJavaScript.
 * Neither exists before hand, so each is created from scratch.
 */
YourGlobal.namespace("Books.MaintainableJavaScript");

// you can now start using the namespace
YourGlobal.Books.MaintainableJavaScript.author = "Nicholas C. Zakas";

/*
 * Leaves YourGlobal.Books alone and adds HighPerformanceJavaScript to it.
 * This leaves YourGlobal.Books.MaintainableJavaScript intact.
 */
YourGlobal.namespace("Books.HighPerformanceJavaScript");

// still a valid reference
console.log(YourGlobal.Books.MaintainableJavaScript.author);

// You can also start adding new properties right off the method call
YourGlobal.namespace("Books").ANewBook = {};

YUI.add("module-name", function(Y) {

    // module body

}, "version", { requires: [ "dependency1", "dependency2" ] });

YUI.add("my-books", function(Y) {

    // Add a namespace
    Y.namespace("Books.MaintainableJavaScript");

    Y.Books.MaintainableJavaScript.author = "Nicholas C. Zakas";

}, "1.0.0", { requires: [ "dependency1", "dependency2" ] });

YUI().use("my-books", "another-module", function(Y) {

    console.log(Y.Books.MaintainableJavaScript.author);

});

define("module-name", [ "dependency1", "dependency2" ],
        function(dependency1, dependency2) {

    // module body

});

define("my-books", [ "dependency1", "dependency2" ],
        function(dependency1, dependency2) {

    var Books = {};
    Books.MaintainableJavaScript = {
        author: "Nicholas C. Zakas"
    };

    return Books;
});

define([ "dependency1", "dependency2" ],
        function(dependency1, dependency2) {

    var Books = {};
    Books.MaintainableJavaScript = {
        author: "Nicholas C. Zakas"
    };

    return Books;
});

// load AMD module in Dojo
var books = dojo.require("my-books");

console.log(books.MaintainableJavaScript.author);

// load AMD module with RequireJS
require([ "my-book" ], function(books) {

    console.log(books.MaintainableJavaScript.author);

});

It is possible to inject your JavaScript into a page without creating a single global variable. This approach is quite limited, so it is useful only in some very specific situations. The most common situation is with a completely standalone script that doesn’t have to be accessed by any other scripts. This situation may occur because all of the necessary scripts are combined into one file, or because the script is small and being inserted into a page that it shouldn’t interfere with. The most common use case is in creating a bookmarklet.

Bookmarklets are unique in that they don’t know what’s going to be on the page and don’t want the page to know that they are present. The end result is a need for a zero-global embedding of the script, which is accomplished by using an immediate function invocation and placing all of the script inside of the function. For example:

(function(win) {

    var doc = win.document;

    // declare other variables here

    // other code goes here

}(window));

This immediately invoked function passes in the window object so that the scripts needn’t directly access any global variables. Inside the function, the doc variable holds a reference to the document object. As long as the function doesn’t modify window or doc directly and all variables are declared using the var keyword, this script will result in no globals being injected into the page. You can further avoid creating globals by putting the function into strict mode (for browsers that support it):

(function(win) {

    "use strict";

    var doc = win.document;

    // declare other variables here

    // other code goes here

}(window));

This function wrapper can now be used for scripts that don’t want to create any global objects. As mentioned previously, this pattern is of limited use. Any script that needs to be used by other scripts on the page cannot use the zero-global approach. A script that must be extended or modified during runtime cannot use the zero-global approach, either. However, if you have a small script that doesn’t need to interact with any other scripts on the page, the zero-global approach is something to keep in mind.

Most developers are familiar with the event object that is passed into an event handler when the event is fired. The event object contains all of the information related to the event, including the event target as well as additional data based on the event type. Mouse events expose additional location information on the event object, keyboard events expose information about keys that have been pressed, and touch events expose information about the location and duration of touches. All of this information is provided so that the UI can react appropriately.

In many cases, however, you end up using a very small subset of the information present on event. Consider the following:

// Bad
function handleClick(event) {
    var popup = document.getElementById("popup");
    popup.style.left = event.clientX + "px";
    popup.style.top = event.clientY + "px";
    popup.className = "reveal";
}

// addListener() from Chapter 5
addListener(element, "click", handleClick);

This code uses just two properties from the event object: clientX and clientY. These properties are used to position an element on the page before showing it to the user. Even though this code seems relatively simple and unproblematic, it’s actually a bad pattern to use in code because of the limitations it imposes.

The previous example’s first problem is that the event handler contains application logic. Application logic is functionality that is related to the application rather than related to the user’s action. In the previous example, the application logic is displaying a pop up in a particular location. Even though this action should happen when the user clicks on a particular element, this may not always be the case.

It’s always best to split application logic from any event handler, because the same logic may need to be triggered by different actions in the future. For example, you may decide later that the pop up should be displayed when the user moves the cursor over the element, or when a particular key is pressed on the keyboard. Then you may end up accidentally duplicating the code into a second or third event handler attaching the same event handler to handle multiple events.

Another downside to keeping application logic in the event handler is for testing. Tests need to trigger functionality directly without going through the overhead of actually having someone click an element to get a reaction. By having application logic inside of event handlers, the only way to test is by causing the event to fire. That’s usually not the best way to test, even though some testing frameworks are capable of simulating events. It would be better to trigger the functionality with a simple function call.

You should always separate application logic from event-handling code. The first step in refactoring the previous example is to move the pop up–handling code into its own function, which will likely be on the one global object you’ve defined for your application. The event handler should also be on the same global object, so you end up with two methods:

// Better - separate application logic
var MyApplication = {

    handleClick: function(event) {
        this.showPopup(event);
    },

    showPopup: function(event) {
        var popup = document.getElementById("popup");
        popup.style.left = event.clientX + "px";
        popup.style.top = event.clientY + "px";
        popup.className = "reveal";    
    }

};

addListener(element, "click", function(event) {
    MyApplication.handleClick(event);
});

The MyApplication.showPopup() method now contains all of the application logic previously contained in the event handler. The MyApplication.handleClick() method now does nothing but call MyApplication.showPopup(). With the application logic separated out, it’s easier to trigger the same functionality from multiple points within the application without relying on specific events to fire. But this is just the first step in unraveling this event-handling code.

After splitting out application logic, the next problem with the previous example is that the event object is passed around. It’s passed from the anonymous event handler to MyApplication.handleClick(), then to MyApplication.showPopup(). As mentioned previously, the event object has potentially dozens of additional pieces of information about the event, and this code only uses two of them.

Application logic should never rely on the event object to function properly for the following reasons:

These issues are both undesirable in a large-scale web application. Lack of clarity is what leads to bugs.

The best approach is to let the event handler use the event object to handle the event and then hand off any required data to the application logic. For example, the MyApplication.showPopup() method requires only two pieces of data: an x-coordinate and a y-coordinate. The method should then be rewritten to accept those as arguments:

// Good
var MyApplication = {

    handleClick: function(event) {
        this.showPopup(event.clientX, event.clientY);
    },

    showPopup: function(x, y) {
        var popup = document.getElementById("popup");
        popup.style.left = x + "px";
        popup.style.top = y + "px";
        popup.className = "reveal";    
    }

};

addListener(element, "click", function(event) {
    MyApplication.handleClick(event);   // this is okay
});

In this rewritten code, MyApplication.handleClick() now passes in the x-coordinate and y-coordinate to MyApplication.showPopup() instead of passing the entire event object. It’s very clear what MyApplication.showPopup() expects to be passed in, and it’s quite easy to call that logic directly from a test or elsewhere in the code, such as:

// Great victory!
MyApplication.showPopup(10, 10);

When handling events, it is best to let the event handler be the only function that touches the event object. The event handler should do everything necessary using the event object before delegating to some application logic. Thus actions such as preventing the default action or stopping event bubbling should be done strictly in the event handler, as in:

// Good
var MyApplication = {

    handleClick: function(event) {

        // assume DOM Level 2 events support
        event.preventDefault();            
        event.stopPropagation();

        // pass to application logic
        this.showPopup(event.clientX, event.clientY);
    },

    showPopup: function(x, y) {        
        var popup = document.getElementById("popup");
        popup.style.left = x + "px";
        popup.style.top = y + "px";
        popup.className = "reveal";    
    }

};

addListener(element, "click", function(event) {
    MyApplication.handleClick(event);   // this is okay
});

In this code, MyApplication.handleClick() is the defined event handler, so it makes the calls to event.preventDefault() and event.stopPropagation() before passing data to the application logic, which is exactly how the relationship between event handlers and the application should work. Because the application logic no longer depends on event, it’s easy to use that same logic in multiple places as well as to write tests.

There are five primitive types in JavaScript: string, number, boolean, null, and undefined. If you are expecting a value to be a string, number, boolean, or undefined, then the typeof operator is your best option. The typeof operator works on a variable and returns a string indicating the type of value:

Basic syntax for typeof is as follows:

typeof variable

You may also see typeof used in this manner:

typeof(variable)

Although this is valid JavaScript syntax, this pattern makes typeof appear to be a function instead of an operator. For this reason, the pattern without parentheses is recommended.

Using typeof for detecting these four primitive value types is the safest way to code defensively. Here are some examples:

// detect a string
if (typeof name === "string") {
    anotherName = name.substring(3);
}

// detect a number
if (typeof count === "number") {
    updateCount(count);
}

// detect a boolean
if (typeof found === "boolean" && found) {
    message("Found!");
}

// detect undefined
if (typeof MyApp === "undefined") {
    MyApp = {    
        // code        
    };
}

The typeof operator is also unique in that it can be used on an undeclared variable without throwing an error. Both undeclared variables and variables whose value is undefined return “undefined” when typeof is used.

The last primitive type, null, is the one that you normally shouldn’t be testing for. As stated earlier, comparing simply against null generally doesn’t give you enough information about whether the value is expected. There is one exception: if one of the expected values is actually null, then it is okay to test for null directly. The comparison should be done using either === or !== against null. For example:

// If you must test for null, this is the way to do it
var element = document.getElementById("my-div");
if (element !== null) { 
    element.className = "found";
}

It is entirely possible for document.getElementById() to return null if the given DOM element isn’t found. The method will return either null or an element. Because null is one of the expected outcomes, it’s okay to test for it using !==.

Reference values are also known as objects. In JavaScript, any value that isn’t a primitive is definitely a reference. There are several built-in reference types such as Object, Array, Date, and Error, just to name a few. The typeof operator is of little use for reference values, because it returns “object” for any type of object:

console.log(typeof {});             // "object"
console.log(typeof []);             // "object"
console.log(typeof new Date());     // "object"
console.log(typeof new RegExp());   // "object"

Another downside to using typeof for objects is that typeof returns “object” for null values as well:

console.log(typeof null);           // "object"

This quirk, which has been recognized as a serious bug in the specification, prevents accurate detection of null using typeof.

The instanceof operator is the best way to detect values of a particular reference type. Basic syntax for instanceof is:

value instanceof constructor

Here are some examples:

// detect a Date
if (value instanceof Date) {
    console.log(value.getFullYear());
}

// detect a RegExp
if (value instanceof RegExp) {
    if (value.test(anotherValue)) {
        console.log("Matches");
    }
}

// detect an Error
if (value instanceof Error) {
    throw value;
}

An interesting feature of instanceof is that it not only checks the constructor used to create the object but also checks the prototype chain. The prototype chain contains information about the inheritance pattern used to define the object. For instance, every object inherits from Object by default, so every object returns true for value instanceof Object. For example:

var now = new Date();

console.log(now instanceof Object);     // true
console.log(now instanceof Date);       // true

Due to this behavior, it’s typically not good enough to use value instanceof Object when you’re expecting a particular type of object.

The instanceof operator also works with custom types that you’ve defined for yourself. For instance:

function Person(name) {
    this.name = name;
}

var me = new Person("Nicholas");

console.log(me instanceof Object);      // true
console.log(me instanceof Person);      // true

This example creates a custom Person type. The me variable is an instance of Person, so me instanceof Person is true. As mentioned previously, all objects are also considered instances of Object, so me instanceof Object is also true.

The instanceof operator is the only good way to detect custom types in JavaScript. It’s also good to use for almost all built-in JavaScript types. There is, however, one serious limitation.

Suppose that an object from one browser frame (frame A) is passed into another (frame B). Both frames have the constructor function Person defined. If the object from frame A is an instance of Person in frame A, then the following rules apply:

// true
frameAPersonInstance instanceof frameAPerson

// false
frameAPersonInstance instanceof frameBPerson

Because each frame has its own copy of Person, it is considered an instance of only that frame’s copy of Person, even though the two definitions may be identical.

This issue is a problem not just for custom types but also for two very important built-in types: functions and arrays. For these two types, you don’t want to use instanceof at all.

function myFunc() {}

// Bad
console.log(myFunc instanceof Function);        // true

function myFunc() {}

// Good
console.log(typeof myFunc === "function");       // true

// Internet Explorer 8 and earlier
console.log(typeof document.getElementById);        // "object"
console.log(typeof document.createElement);         // "object"
console.log(typeof document.getElementsByTagName);  // "object"

// detect DOM method
if ("querySelectorAll" in document) {
    images = document.querySelectorAll("img");
}

// Duck typing arrays
function isArray(value) {
    return typeof value.sort === "function";
}

function isArray(value) {
    return Object.prototype.toString.call(value) === "[object Array]";
}

function isArray(value) {
    if (typeof Array.isArray === "function") {
        return Array.isArray(value);
    } else {
        return Object.prototype.toString.call(value) === "[object Array]";
    }
}

Another time when when developers typically use null (and also undefined) is when trying to determine whether a property is present in an object. For example:

// Bad: Checking falsyness
if (object[propertyName]) {
    // do something
}

// Bad: Compare against null
if (object[propertyName] != null) {
    // do something
}

// Bad: Compare against undefined
if (object[propertyName] != undefined) {
    // do something
}

Each of these examples is actually checking the value of the property with the given name rather than the existence of the property with the given name, which can result in errors when you’re dealing with falsy values such as 0, "" (empty string), false, null, and undefined. After all, these are all valid values for properties. For example, if the property is keeping track of a number, the value might very well be zero. In that case, the first example will likely cause a bug. Likewise, if the property value could be null or undefined, all three examples can cause bugs.

The best way to detect the presence of a property is to use the in operator. The in operator simply checks for the presence of the named property without reading its value, avoiding ambiguity with statements such as those earlier in this section. If the property either exists on the instance or is inherited from the object’s prototype, the in operator returns true. For example:

var object = {
    count: 0,
    related: null
};

// Good
if ("count" in object) {
    // this executes
}

// Bad: Checking falsy values
if (object["count"]) {
    // this doesn't execute
}

// Good
if ("related" in object) {
    // this executes
}

// Bad: Checking against null
if (object["related"] != null) {
    // doesn't execute
}

If you only want to check for the existence of the property on the object instance, then use the hasOwnProperty() method. All JavaScript objects that inherit from Object have this method, which returns true when the property exists on the instance (if the property only exists on the prototype, in which case it returns false). Keep in mind that DOM objects in Internet Explorer 8 and earlier do not inherit from Object and therefore do not have this property. That means you’ll need to check for the existence of hasOwnProperty() before using it on potential DOM objects (if you know the object isn’t from the DOM, you can omit this step).

// Good for all non-DOM objects
if (object.hasOwnProperty("related")) {
    //this executes
}

// Good when you're not sure
if ("hasOwnProperty" in object && object.hasOwnProperty("related")) {
    //this executes
}

Because of Internet Explorer 8 and earlier, I tend to use the in operator whenever possible and only use hasOwnProperty() when I need to be sure of an instance property.

Whenever you want to check for the existence of the property, make sure to use the in operator or hasOwnProperty(). Doing so can avoid a lot of bugs.

Configuration data is any hardcoded value in an application. Consider the following example:

// Configuration data embedded in code
function validate(value) {
    if (!value) {
        alert("Invalid value");
        location.href = "/errors/invalid.php";
    }
}

function toggleSelected(element) {
    if (hasClass(element, "selected")) {
        removeClass(element, "selected");
    } else {
        addClass(element, "selected");
    }
}

There are three pieces of configuration data in this code. The first is the string “Invalid value,” which is displayed to the user. As a UI string, there’s a good chance that it will change frequently. The second is the URL /errors/invalid.php. URLs tend to change as development progresses, due to architectural decisions. The third is the CSS class name “selected.” This class name is used three times, meaning that a class name change requires changes in three different places, increasing the likelihood that one will be missed.

These are all considered configuration data, because they are hardcoded values that may change in the future. The following are all examples of configuration data:

The key point to remember about configuration data is that it changes, and you don’t want to be modifying your JavaScript source code because someone changed his mind about a message to display on the home page.

The first step in separating configuration data from code is to externalize the configuration data, which means getting the data out of the middle of your JavaScript code. Here’s the previous example with the configuration data externalized:

// Configuration data externalized
var config = {
    MSG_INVALID_VALUE:  "Invalid value",
    URL_INVALID:        "/errors/invalid.php",
    CSS_SELECTED:       "selected"
};

function validate(value) {
    if (!value) {
        alert(config.MSG_INVALID_VALUE);
        location.href = config.URL_INVALID;
    }
}

function toggleSelected(element) {
    if (hasClass(element, config.CSS_SELECTED)) {
        removeClass(element, config.CSS_SELECTED);
    } else {
        addClass(element, config.CSS_SELECTED);
    }
}

This example stores all of the configuration data in the config object. Each property of config holds a single piece of data, and each property name has a prefix indicating the type of data (MSG for a UI message, URL for a URL, and CSS for a class name). The naming convention is, of course, a matter of preference. The important part of this code is that all of the configuration data has been removed from the functions and replaced with placeholders from the config object.

Externalizing the configuration data means that anyone can go in and make a change without introducing an error in the application logic. It also means that the entire config object can be moved into its own file, so edits are made far away from the code that uses the data.

Configuration data is best stored in a separate file to create a clean separation between it and application logic. A good starting point is to have a separate JavaScript file for configuration data. Once the configuration data is in a separate file, it opens up more possibilities for managing that data. A worthwhile option is moving your configuration data into a non-JavaScript file.

Even though you’re writing a JavaScript application, JavaScript isn’t a great way to store configuration data. That’s because the syntax is still that of a programming language, so you need to be sure you haven’t introduced syntax errors. If you end up concatenating JavaScript files together, a syntax error in a single line breaks the overall application. Configuration data truly belong in files that are hard to format incorrectly, and once you have that file, it is trivial to convert the configuration data into a JavaScript format automatically.

One of my favorite formats for configuration data is a Java properties file. Java properties files are simple name-value pairs in which each pair takes a single line (unless you put in a multiple-line sequence) in the form name=value. It doesn’t matter if there are spaces around the equals sign, so even that syntax isn’t hard to get right. Comments are indicated by preceding the line with a # character. Here’s an example:

# UI Strings
MSG_INVALID_VALUE = Invalid value

# URLs
URL_INVALID = /errors/invalid.php

# CSS Classes
CSS_SELECTED = selected

This properties file contains the same properties as the config object from the previous example. Notice how much simpler the file layout is. There are no quoted strings, which means that you don’t have to worry about proper escaping or forgetting to close a string. There are also no semicolons or commas to worry about. You can simply put in your data and not worry about JavaScript syntax at all.

The next step is to convert this file into something that’s usable by JavaScript. There are generally three formats in which you want your configuration data. The first is JSON, which is useful when embedding your data into another file or setting up data for retrieval from the server. For instance:

{"MSG_INVALID_VALUE":"Invalid value","URL_INVALID":"/errors/invalid.php",
"CSS_SELECTED":"selected"}

The second is JSONP (JSON with padding), which returns the JSON structure wrapped in a function:

myfunc({"MSG_INVALID_VALUE":"Invalid value","URL_INVALID":"/errors/invalid.php",
        "CSS_SELECTED":"selected"});

Because JSONP is valid JavaScript, you can concatenate this code into other files to give them access to the data.

The last option is plain JavaScript, in which you assign the JSON object to a variable to use later, as in:

var config={"MSG_INVALID_VALUE":"Invalid value","URL_INVALID":"/errors/invalid.php",
            "CSS_SELECTED":"selected"};

As with JSONP, the plain JavaScript version can be combined with other JavaScript files easily once produced.

For these common use cases, I have created a tool called Props2Js that reads Java properties files and outputs the data into one of these three formats. Props2Js is free and open source, available at https://github.com/nzakas/props2js/. It works like this:

java -jar props2js-0.1.0.jar --to jsonp --name myfunc 
    --output result.js source.properties

The --to option specifies the output format, either “js,” “json,” or “jsonp.” The --name option specifies either the variable name (for “js”) or the function name (for “jsonp”); this option is ignored for “json.” The --output option specifies the file to write the data into. So this line takes the Java properties file named source.properties and outputs JSONP with a callback function of myfunc to a file named result.js.

Using a tool like Props2Js allows you to keep configuration data in a simpler file format and then easily convert your configuration data into a format that is usable by JavaScript later.

An error occurs in programming when something unexpected happens. Maybe the incorrect value was passed into a function or a mathematical operation had an invalid operand. Programming languages define a base set of rules that when deviated from, result in errors so that the developer can fix the code. Debugging would be nearly impossible if errors weren’t thrown and reported back to you. If everything failed silently, it would take you a long time to notice that there was an issue in the first place, let alone isolate and fix it. Errors are the friends of developers, not enemies.

The problem with errors is that they tend to pop up in unexpected places and at unexpected times. To make matters worse, the default error messages are usually too terse to really explain what went wrong. JavaScript error messages are notoriously uninformative and cryptic (especially in old versions of Internet Explorer), which only compounds the problem. Imagine if an error popped up with a message that said, “This function failed because this happened.” Instantly, your debugging task becomes easier. This ease is the advantage of throwing your own errors.

It helps to think of errors as built-in failure cases. It’s always easier to plan for a failure at a particular point in code than it is to anticipate failure everywhere. This is a very common practice in product design, not just in code. Cars are built with crumple zones, areas of the frame that are designed to collapse in a predictable way when impacted. Knowing how the frame will react in a crash—specifically, which parts will fail—allows the manufacturers to ensure passenger safety. Your code can be constructed in the same way.

Throwing errors in your JavaScript is arguably more valuable than in any other language due to the complexities involved in web debugging. You can throw an error by using the throw operator and providing an object to throw. Any type of object can be thrown; however, an Error object is the most typical to use:

throw new Error("Something bad happened.")

The built-in Error type is available in all JavaScript implementations, and the constructor takes a single argument, which is the error message. When you throw an error in this way, and the error isn’t caught via a try-catch statement, the browser displays the value of message in the browser’s typical way. Most browsers now have a console to which error information is output whenever an error occurs. In other words, any error you throw is treated the same way as an error that you didn’t throw.

Inexperienced developers sometimes throw errors by just providing a string, such as:

// Bad
throw "message";

Doing so will cause an error to be thrown, but not all browsers respond the way you’d expect. Firefox, Opera, and Chrome each display an “uncaught exception” message and then include the message string. Safari and Internet Explorer simply throw an “uncaught exception” error and don’t provide the message string at all, which isn’t very useful for debugging purposes.

Of course, you can throw any type of data that you’d like. There are no rules prohibiting specific data types:

throw { name: "Nicholas" };
throw true;
throw 12345;
throw new Date();

The only thing to remember is that throwing any value will result in an error if it’s not caught via a try-catch statement. Firefox, Opera, and Chrome all call String() on the value that was thrown to display something logical as the error message; Safari and Internet Explorer do not. The only surefire way to have all browsers display your custom error message is to use an Error object.

Throwing your own error allows you to provide the exact text to be displayed by the browser. Instead of just line and column numbers, you can include any information that you’ll need to successfully debug the issue. I recommend that you always include the function name in the error message as well as the reason why the function failed. Consider the following function:

function getDivs(element) {
    return element.getElementsByTagName("div");
}

This function’s purpose is to retrieve all <div> elements that are a descendant of element. It’s quite common for functions that interact with the DOM to be passed null values where DOM elements should be. What happens if null is passed to this function? You’ll get a cryptic error message such as “object expected.” Then you’ll need to look at the execution stack to actually locate the source of the problem. Debugging becomes much easier by throwing an error:

function getDivs(element) {

    if (element && element.getElementsByTagName) {
        return element.getElementsByTagName("div");
    } else {
        throw new Error("getDivs(): Argument must be a DOM element.");
    }
}

Now that getDivs() throws an error, any time element doesn’t meet the criteria for continuing, an error is thrown that very clearly states the problem. If this error shows up in the browser console, you know immediately where to start debugging and that the most likely cause is a call to retrieve a DOM element is returning null at some point.

I like to think of throwing errors as leaving sticky notes for myself as to why something failed.

Understanding how to throw errors is just one part of the equation; understanding when to throw errors is the other. Because JavaScript doesn’t have type or argument checking, a lot of developers incorrectly assume that they should implement these types of checking for every function. Doing so is impractical and can adversely affect the script’s overall performance. Consider this function, which tries to implement overly aggressive type checking:

// Bad: Too much error checking
function addClass(element, className) {
    if (!element || typeof element.className != "string") {
        throw new Error("addClass(): First argument must be a DOM element.");
    }

    if (typeof className != "string") {
        throw new Error("addClass(): Second argument must be a string.");
    }

    element.className += " " + className;
}

This function simply adds a CSS class to a given element; however, most of the function is taken up doing error checking. Even though it may be tempting to check each argument in every function (mimicking statically typed languages), doing so is often overkill in JavaScript. The key is to identify parts of the code that are likely to fail in a particular way and throw errors only there. In short, throw errors only where errors will already occur.

The most likely cause of an error in the previous example is a null reference being passed in to the function. If the second argument is null, or a number, or a boolean, no error will be thrown, because JavaScript will coerce the value into a string. That may mean that the resulting display of the DOM element isn’t as expected, but it certainly doesn’t rise to the level of serious error. So I would check only for the DOM element, as in:

// Good
function addClass(element, className) {
    if (!element || typeof element.className != "string") {
        throw new Error("addClass(): First argument must be a DOM element.");
    }

    element.className += " " + className;
}

If a function is only ever going to be called by known entities, error checking is probably unnecessary (this is the case with private functions); if you cannot identify all the places where a function will be called ahead of time, then you’ll likely need some error checking and will even more likely benefit from throwing your own errors. The best place for throwing errors is in utility functions, such as the addClass() function, that are a general part of the scripting environment and may be used in any number of places, which is precisely the case with JavaScript libraries.

All JavaScript libraries should throw errors from their public interfaces for known error conditions. Large libraries such as jQuery, YUI, and Dojo can’t possibly anticipate when and where you’ll be calling their functions. It’s their job to tell you when you’re doing stupid things, because you shouldn’t have to debug into library code to figure out what went wrong. The call stack for an error should terminate in the library’s interface and no deeper. There’s nothing worse than seeing an error that’s 12 functions deep into a library; library developers have a responsibility to prevent this from happening.

The same goes for private JavaScript libraries. Many web applications have their own proprietary JavaScript libraries either built with or in lieu of the well-known public options. The goal of libraries is to make developers’ lives easier, which is done by providing an abstraction away from the dirty implementation details. Throwing errors helps to keep those dirty implementation details hidden safely away from developers.

Some good general rules of thumb for throwing errors:

Remember that the goal isn’t to prevent errors—it’s to make errors easier to debug when they occur.

JavaScript provides a try-catch statement that is capable of intercepting thrown errors before they are handled by the browser. The code that might cause an error comes in the try block and code that handles the error goes into the catch block. For instance:

try {
    somethingThatMightCauseAnError();
} catch (ex) {
    handleError(ex);
}

When an error occurs in the try block, execution immediately stops and jumps to the catch block, where the error object is provided. You can inspect this object to determine the best course of action to recover from the error.

There is also a finally clause that can be added. The finally clause contains code that will be executed regardless of whether an error occurs. For example:

try {
    somethingThatMightCauseAnError();
} catch (ex) {
    handleError(ex);
} finally {
    continueDoingOtherStuff();
}

The finally clause is a little bit tricky to work with in certain situations. For example, if the try clause contains a return statement, it won’t actually return until finally has been evaluated. Due to this trickiness, finally is used infrequently, but it is a powerful tool for error handling if necessary.

// Bad
try {
    somethingThatMightCauseAnError();
} catch (ex) {
    // noop
}

ECMA-262 specifies seven error object types. These are used by the JavaScript engine when various error conditions occur and can also be manually created:

Understanding that there are different types of errors can make it easier to handle them. All error types inherit from Error, so checking the type with instanceof Error doesn’t give you any useful information. By checking for the more specific error types, you get more robust error handling:

try {
    // something that causes an error
} catch (ex) {
    if (ex instanceof TypeError) {
        // handle the error
    } else if (ex instanceof ReferenceError) {
        // handle the error
    } else {
        // handle all others
    }
}

If you’re throwing your own errors, and you’re throwing a data type that isn’t an error, you can more easily tell the difference between your own errors and the ones that the browser throws. There are, however, several advantages to throwing actual Error objects instead of other object types.

First, as mentioned before, the error message will be displayed in the browser’s normal error-handling mechanism. Second, the browser attatches extra information to Error objects when they are thrown. These vary from browser to browser, but they provide contextual information for the error such as line number and column number and, in some browsers, stack and source information. Of course, you lose the ability to distinguish between your own errors and browser-thrown ones if you just use the Error constructor.

The solution is to create your own error type that inherits from Error. Doing so allows you to provide additional information as well as distinguish your errors from the errors that the browser throws. You can create a custom error type using the following pattern:

function MyError(message) {
    this.message = message;
}

MyError.prototype = new Error();

There are two important parts of this code: the message property, which is necessary for browsers to know the actual error string, and setting the prototype to an instance of Error, which identifies the object as an error to the JavaScript engine. Now you can throw an instance of MyError and have the browser respond as if it’s a native error:

throw new MyError("Hello world!");

The only caveat to this approach is that Internet Explorer 8 and earlier won’t display the error message. Instead, you’ll see the generic “Exception thrown but not caught” error message. The big advantage of this approach is that custom error objects allow you to test specifically for your own errors:

try {
    // something that causes an error
} catch (ex) {
    if (ex instanceof MyError) {
        // handle my own errors
    } else {
        // handle all others
    }
}

If you’re always catching any errors you throw, then Internet Explorer’s slight stupidity shouldn’t matter all that much. The benefits from such an approach are huge in a system with proper error handling. This approach gives you much more flexibility and information for determining the correct course of action for a given error.

You own an object when your code creates the object. The code that creates the object may not have necessarily been written by you, but as long as it’s the code you’re responsible for maintaining, then you own that object. For instance, the YUI team owns the YUI object, and the Dojo team owns the dojo object. Even though the original person who wrote the code defining the object may not work on it anymore, the respective teams are still the owners of those objects.

When you use a JavaScript library in a project, you don’t automatically become the owner of its objects. In a multiple-developer project, everyone is assuming that the library objects work as they are documented. If you’re using YUI and make modifications to the YUI object, then you’re setting up a trap for your team. Someone is going to fall in, and it’s going to cause a problem.

Remember, if your code didn’t create the object, then it’s not yours to modify, which includes:

All of these objects are part of your project’s execution environment. You can use these pieces as they are already provided to you or create new functionality; you should not modify what’s already there.

Enterprise software needs a consistent and dependable execution environment to be maintainable. In other languages, you consider existing objects as libraries for you to use to complete your task. In JavaScript, you might see existing objects as a playground in which you can do anything you want. You should treat the existing JavaScript objects as you would a library of utilities:

When you’re the only one working on a project, it’s easy to get away with these types of modification because you know them and expect them. When working with a team on a large project, making changes like this causes mass confusion and a lot of lost time.

// Bad
document.getElementById = function() {
    return null;        // talk about confusing
};

// Bad
document._originalGetElementById = document.getElementById;
document.getElementById = function(id) {
    if (id == "window") {
        return window;
    } else {
        return document._originalGetElementById(id);
    }
};

// Bad - adding method to DOM object
document.sayImAwesome = function() {
    alert("You're awesome.");
};

// Bad - adding method to native object
Array.prototype.reverseSort = function() {
    return this.sort().reverse();
};

// Bad - adding method to library object
YUI.doSomething = function() {
    // code
};

document.getElementByClassName("selected").each(doSomething);

if (!document.getElementsByClassName) {

    document.getElementsByClassName = function(classes) {
        // non-native implementation
    };

}

// Bad - eliminating a DOM method
document.getElementById = null;

var person = {
    name: "Nicholas"
};

delete person.name;

console.log(person.name);       // undefined

// No effect
delete document.getElementById;

console.log(document.getElementById("myelement"));  // stil works

Modifying objects you don’t own is a solution to some problems. It usually doesn’t happen organically; it happens because a developer has come across a problem that object modification solves. However, there is almost always more than one solution to any given problem. Most computer science knowledge has evolved out of solving problems in statically typed languages such as Java. There are many approaches, called design patterns, to extending existing objects without directly modifying those objects.

The most popular form of object augmentation outside of JavaScript is inheritance. If there’s a type of object that does most of what you want, then you can inherit from it and add additional functionality. There are two basic forms of inheritance in JavaScript: object-based and type-based.

var person = {
    name: "Nicholas",
    sayName: function() {
        alert(this.name);
    }
};

var myPerson = Object.create(person);

myPerson.sayName();     // pops up "Nicholas"

myPerson.sayName = function() {
    alert("Anonymous");
};

myPerson.sayName();     // pops up "Anonymous"
person.sayName();       // pops up "Nicholas"

var myPerson = Object.create(person, {
    name: { 
        value: "Greg"
    }
});

myPerson.sayName();     // pops up "Greg"
person.sayName();       // pops up "Nicholas"

function MyError(message) {
    this.message = message;
}

MyError.prototype = new Error();

var error = new MyError("Something bad happened.");

console.log(error instanceof Error);        // true
console.log(error instanceof MyError);      // true

function Person(name) {
    this.name;
}

function Author(name) {
    Person.call(this, name);    // inherit constructor
}

Author.prototype = new Person();

function DOMWrapper(element) {    
    this.element = element;
}

DOMWrapper.prototype.addClass = function(className) {
    this.element.className += " " + className;
};

DOMWrapper.prototype.remove = function() {
    this.element.parentNode.removeChild(this.element);
};

// Usage
var wrapper = new DOMWrapper(document.getElementById("my-div"));

// add a CSS class
wrapper.addClass("selected");

// remove the element
wrapper.remove();

JavaScript polyfills (also known as shims) became popular when ECMAScript 5 and HTML5 features started being implemented in browsers. A polyfill implements functionality that is already well-defined and implemented natively in newer browsers. For example, ECMAScript 5 added the forEach() method for arrays. This method can be implemented using ECMAScript 3, so older browsers can use forEach() as if it were a newer browser. The key to polyfills is that they implement native functionality in a completely compatible way. Because the functionality exists in some browsers, it’s possible to test whether different cases are handled in a standards-compliant manner.

Polyfills often add new methods to objects they don’t own to achieve their end goal. I’m not a fan of polyfills, but I do understand why people use them. Polyfills are marginally safer than other types of object modification, because the native implementation already exists and can be worked with. Polyfills add new methods only when the native one isn’t present and the nonnative version behaves the same as the native one.

The advantage of polyfills is that you can easily remove them when you’re supporting only browsers with the native functionality. If you choose to use a polyfill, do your due diligence. Make sure the functionality matches the native version as closely as possible and double-check that the library has unit tests to verify the functionality. The disadvantage of polyfills is that they may not accurately implement the missing functionality, and then you end up with more problems rather than fewer.

For best maintainability, avoid polyfills and instead create a facade over existing native functionality. This approach gives you the most flexibility, which is especially important when native implementations have bugs. In that case, you never want to use the native API directly, because you can’t insulate yourself from the implementation bugs.

ECMAScript 5 introduced several methods to prevent modification of objects. This capability is important to understand, as it’s now possible to lock down objects to ensure that no one, accidentally or otherwise, changes functionality that they shouldn’t. This functionality is supported in Internet Explorer 9+, Firefox 4+, Safari 5.1+, Opera 12+, and Chrome. There are three levels of preventing modification:

Each of these lock-down types has two methods: a method that performs the action and a method that confirms the action was taken. For preventing extensions, Object.preventExtensions() and Object.isExtensible() are used:

var person = {
    name: "Nicholas"
};

// lock down the object
Object.preventExtensions(person);

console.log(Object.isExtensible(person));       // false

person.age = 25;    // fails silently unless in strict mode

In this example, person is locked down to the extension, so Object.isExtensible() is false. Attempting to assign a new property or method will fail silently in nonstrict mode. In strict mode, any attempt to add a new property or method to a nonextensible object causes an error.

To seal an object, use Object.seal(). You can determine whether an object is sealed using Object.isSealed():

// lock down the object
Object.seal(person);

console.log(Object.isExtensible(person));   // false
console.log(Object.isSealed(person));       // true

delete person.name; // fails silently unless in strict mode
person.age = 25;    // fails silently unless in strict mode

When an object is sealed, its existing properties and methods cannot be removed, so attempting to remove name will fail silently in nonstrict mode. In strict mode, attempting to delete a property or method results in an error. Sealed objects are also nonextensible, so Object.isExtensible() returns false.

To freeze an object, use Object.freeze(). You can determine whether an object is frozen using Object.isFrozen():

// lock down the object
Object.freeze(person);

console.log(Object.isExtensible(person));   // false
console.log(Object.isSealed(person));       // true
console.log(Object.isFrozen(person));       // true

person.name = "Greg";   // fails silently unless in strict mode
person.age = 25;        // fails silently unless in strict mode
delete person.name;     // fails silently unless in strict mode

Frozen objects are considered both nonextensible and sealed, so Object.isExtensible() returns false and Object.isSealed() returns true for all frozen objects. The big difference between frozen objects and sealed objects is that you cannot modify any existing properties or methods. Any attempt to do so fails silently in nonstrict mode and throws an error in strict mode.

Preventing modification using these ECMAScript 5 methods is an excellent way to ensure that your objects aren’t modified without your knowledge. If you’re a library author, you may want to lock down certain parts of the core library to make sure they’re not accidentally changed or to enforce where extensions are allowed to live. If you’re an application developer, lock down any parts of the application that shouldn’t change. In both cases, using one of the lock-down methods should happen only after you’ve completely defined all object functionality. Once an object is locked down, it cannot be restored.

If you decide to prevent modification of your objects, I strongly recommend using strict mode. In nonstrict mode, attempts to modify unmodifiable objects always fail silently, which could be very frustrating during debugging. By using strict mode, these same attempts will throw an error and make it more obvious why the modification isn’t working.

The earliest form of browser detection was user-agent detection, a process by which the server (and later the client) looked at the user-agent string and determined the browser. During that time, servers would regularly block certain browsers from viewing anything on the site based solely on the user-agent string. The browser that benefited the most was Netscape Navigator. Netscape was certainly the most capable browser, so websites targeted that browser as the only one that could properly display the site. Netscape’s user-agent string looked like this:

Mozilla/2.0 (Win95; I)

When Internet Explorer was first released, it was essentially forced to duplicate a large part of the Netscape user-agent string to ensure that servers would serve up the site to this new browser. Because most user-agent detection was done by searching for “Mozilla” and then taking the version number after the slash, the Internet Explorer user-agent string was:

Mozilla/2.0 (compatible; MSIE 3.0; Windows 95)

Internet Explorer’s introduction meant that everyone’s user-agent string detection identified Internet Explorer as Netscape. This started a trend of new browsers partially copying the user-agent strings of existing browsers that continued up through the release of Chrome, whose user-agent string contains parts of Safari’s string, which in turn contained parts of Firefox’s string, which in turn contained parts of Netscape’s string.

Fast forward to the year 2005, when JavaScript started to increase in popularity. The browser’s user-agent string, the same one reported to the server, is accessible in JavaScript through navigator.userAgent. User-agent string detection moved into web pages with JavaScript performing the same type of user-agent string detection as the server, such as:

// Bad
if (navigator.userAgent.indexOf("MSIE") > -1) {
    // it's Internet Explorer
} else {
    // it's not
}

As more websites took to user-agent detection in JavaScript, a new group of sites started to fail in browsers. The same problem for bit servers nearly a decade earlier had reemerged in the form of JavaScript.

The big problem is that user-agent string parsing is difficult, due to the way browsers have copied one another to try to ensure compatibility. With every new browser, user-agent detection code needs to be updated, and the time between the browser is released to the time the changed code is deployed could mean untold numbers of people getting a bad user experience.

This isn’t to say that there isn’t any way to use the user-agent string effectively. There are well-written libraries, both in JavaScript and for the server, that provide a reasonably good detection mechanism. Unfortunately, these libraries also require constant updates as browsers continue to evolve and new browsers are released. The overall approach isn’t maintainable over the long term.

User-agent detection should always be the last approach to determining the correct course of action in JavaScript. If you choose user-agent detection, then the safest way to proceed is by detecting only older browsers. For instance, if you need to do something special to make your code work in Internet Explorer 8 and earlier, then you should detect Internet Explorer 8 and earlier rather than trying to detect Internet Explorer 9 and higher, such as:

if (isInternetExplorer8OrEarlier) {
    // handle IE8 and earlier
} else {
    // handle all other browsers
}

The advantage you have in this situation is that the Internet Explorer 8 and earlier user-agent strings are well known and won’t be changing. Even if your code continues to run through the release of Internet Explorer 25, the code will most likely continue to work without further modifications. The opposite isn’t true—you’ll be stuck updating code constantly if you try to detect Internet Explorer 9 and higher.

Looking to use a more sane approach to browser-based conditionals, developers turned to a technique called feature detection. Feature detection works by testing for a specific browser feature and using it only if present. So instead of doing something like this:

// Bad
if (navigator.userAgent.indexOf("MSIE 7") > -1) {
    // do something
}

you should do something like this:

// Good
if (document.getElementById) {
    // do something
}

There is a distinction between these two approaches. The first is testing for a specific browser by name and version; the second is testing for a specific feature, namely document.getElementById. So user-agent sniffing results in knowing the exact browser and version being used (or at least the one being reported by the browser) and feature detection determines whether a given object or method is available. Note that these are two completely different results.

Because feature detection doesn’t rely on knowledge of which browser is being used, only on which features are available, it is trivial to ensure support in new browsers. For instance, when the DOM was young, not all browsers supported document.getElementById(), so there was a lot of code that looked like this:

// Good
function getById (id) {

    var element = null;

    if (document.getElementById) {    // DOM
        element = document.getElementById(id);
    } else if (document.all) {      // IE
        element = document.all[id];
    } else if (document.layers) {    // Netscape <= 4
        element = document.layers[id];
    }

    return element;
}

This is a good and appropriate use of feature detection, because the code tests for a feature and then, if it’s there, uses it. The test for document.getElementById() comes first because it is the standards-based solution. After that come the two browser-specific solutions. If none of these features is available, then the method simply returns null. The best part about this function is that when Internet Explorer 5 and Netscape 6 were released with support for document.getElementById(), this code didn’t need to change.

The previous example illustrates several important parts of good feature detection:

The same approach is used today with the cutting-edge features that browsers have implemented experimentally while the specification is being finalized. For instance, the requestAnimationFrame() method was being finalized toward the end of 2011, at which time several browsers had already implemented their own version with a vendor prefix. The proper feature detection for requestAnimationFrame() looks like this:

// Good
function setAnimation (callback) {

    if (window.requestAnimationFrame) {                 // standard
        return requestAnimationFrame(callback);
    } else if (window.mozRequestAnimationFrame) {       // Firefox
        return mozRequestAnimationFrame(callback);
    } else if (window.webkitRequestAnimationFrame) {    // WebKit
        return webkitRequestAnimationFrame(callback);
    } else if (window.oRequestAnimationFrame) {         // Opera
        return oRequestAnimationFrame(callback);
    } else if (window.msRequestAnimationFrame) {        // IE
        return msRequestAnimationFrame(callback);
    } else {
        return setTimeout(callback, 0);
    }

}

This code starts by looking for the standard requestAnimationFrame() method, and only if it’s not found does it continue to look for the browser-specific implementation. The very last option, for browsers with no support, is to use setTimeout() instead. Once again, this code won’t need to be updated even after the browsers have switched to using a standards-based implementation.

One inappropriate use of feature detection is called feature inference. Feature inference attempts to use multiple features after validating the presence of only one. The presence of one feature is inferred by the presence of another. The problem is, of course, that inference is an assumption rather than a fact, and that can lead to maintenance issues. For example, here’s some older code using feature inference:

// Bad - uses feature inference
function getById (id) {

    var element = null;

    if (document.getElementsByTagName) {    // DOM
        element = document.getElementById(id);
    } else if (window.ActiveXObject) {      // IE
        element = document.all[id];
    } else {                                // Netscape <= 4
        element = document.layers[id];
    }

    return element;
}

This function is feature inference at its worst. There are several inferences being made:

You cannot infer the existence of one feature based on the existence of another feature. The relationship between two features is tenuous at best and circumstantial at worst. It’s like saying, “If it looks like a duck, then it must quack like a duck.”

Somewhere along the lines, a lot of web developers grew confused about the distinction between user-agent detection and feature detection. Code started being written similar to this:

// Bad
if (document.all) {  // IE
    id = document.uniqueID;
} else {
    id = Math.random();
}

The problem with this code is that a test for document.all is used as an implicit check for Internet Explorer. Once it’s known that the browser is Internet Explorer, the assumption is that it’s safe to use document.uniqueID, which is IE-specific. However, all you tested was whether document.all is present, not whether the browser is Internet Explorer. Just because document.all is present doesn’t mean that document.uniqueID is also available. There’s a false implication that can cause the code to break.

As a clearer statement of this problem, developers started replacing code like this:

var isIE = navigator.userAgent.indexOf("MSIE") > -1;

With code like this:

// Bad
var isIE = !!document.all;

Making this change indicates a misunderstanding of “don’t use user-agent detection.” Instead of looking for a particular browser, you’re looking for a feature and then trying to infer that it’s a specific browser, which is just as bad. This is called browser inference and is a very bad practice.

Somewhere along the line, developers realized that document.all was not, in fact, the best way to determine whether a browser was Internet Explorer. The previous code was replaced with more specific code, such as this:

// Bad
var isIE = !!document.all && document.uniqueID;

This approach falls into the “too clever” category of programming. You’re trying too hard to identify something by describing an increasing number of identifying aspects. What’s worse is that there’s nothing preventing other browsers from implementing the same capabilities, which will ultimately make this code return unreliable results.

Browser inference even made it into some JavaScript libraries. The following snippet comes from MooTools 1.1.2:

// from MooTools 1.1.2
if (window.ActiveXObject) 
    window.ie = window[window.XMLHttpRequest ? 'ie7' : 'ie6'] = true;
else if (document.childNodes && !document.all && !navigator.taintEnabled) 
    window.webkit = window[window.xpath ? 'webkit420' : 'webkit419'] = true;
else if (document.getBoxObjectFor != null || window.mozInnerScreenX != null) 
    window.gecko = true;

This code tries to determine which browser is being used based on browser inference. There are several problems with this code:

The number of issues with the browser inference code is quite daunting, especially the last one. For every new browser release, MooTools would have had to update this code and get it pushed out to all users quite quickly to avoid code breaking. That’s just not maintainable in the long run.

To understand why browser inference doesn’t work, you need only look back to high school math class, in which logic statements are typically taught. Logic statements are made up of a hypothesis (p) and a conclusion (q) in the form “if p, then q.” You can try altering the statement form to determine truths. There are three ways to alter the statement:

There are two important relationships among the various forms of the statement. If the original statement is true, then the contrapositive is also true. For example, if the original statement was “If it’s a car, then it has wheels” (which is true) then the contrapositive, “if it doesn’t have wheels, then it’s not a car,” is also true.

The second relationship is between the converse and the inverse, so if one is true, then the other must also be true. This makes sense logically, because the relationship between converse and inverse is the same as between original and contrapositive.

Perhaps more important than these two relationships are the relationships that don’t exist. If the original statement is true, then there is no guarantee that the converse is true. This is where feature-based browser detection falls apart. Consider this true statement: “If it’s Internet Explorer, then document.all is implemented.” The contrapositive, “If document.all is not implemented, then it’s not Internet Explorer,” is also true. The converse, “If document.all is implemented, then it’s Internet Explorer,” is not strictly true (some versions of Opera implemented it). Feature-based detection assumes that the converse is always true when, in fact, there is no such relationship.

Adding more parts to the conclusion doesn’t help, either. Consider once again the statement, “If it’s a car, then it has wheels.” The converse is obviously false: “If it has wheels, then it’s a car.” You could try making it more precise: “If it’s a car, then it has wheels and requires fuel.” Check the converse: “If it has wheels and requires fuel, then it’s a car.” Also not true, because an airplane fits that description. So try again: “If it’s a car, then it has wheels, requires fuel, and uses two axles.” Once again, the converse isn’t going to be true.

The problem is fundamental to human language: it’s very hard to use a collection of singular aspects to define the whole. We have the word “car” because it implies a lot of aspects that you would otherwise have to list to identify that thing in which you drive to work. Trying to identify a browser by naming more and more features is the exact same problem. You’ll get close, but it will never be a reliable categorization.

MooTools backed themselves, and their users, into a corner by opting for feature-based browser detection. Mozilla had warned since Firefox 3 that the getBoxObjectFor() method was deprecated and would be removed in a future release. Because MooTools relied on this method to determine whether a browser is Gecko-based, Mozilla’s removal of the method in Firefox 3.6 meant that anyone running older versions of MooTools could have code that was now affected. This situation prompted MooTools to issue a call to upgrade to the most recent version, in which the issue is “fixed.” The explanation:

Feature inference and browser inference are very bad practices that should be avoided at all costs. Straight feature detection is a best practice, and in almost every case, is exactly what you’ll need. Typically, you just need to know if a feature is implemented before using it. Don’t try to infer relationships between features, because you’ll end up with false positives or false negatives.

I won’t go so far as to say never use user-agent detection, because I do believe there are valid use cases. I don’t believe, however, that there are a lot of valid use cases. If you’re thinking about user-agent sniffing, keep this in mind: the only safe way to do so is to target older versions of a specific browser. You should never target the most current browser version or future versions.

My recommendation is to use feature detection whenever possible. If it’s not possible, then fall back to user-agent detection. Never, ever use browser inference, because you’ll be stuck with code that isn’t maintainable and will constantly require updating as browsers continue to evolve.

Regardless of the project type, there are several best practices that apply to JavaScript file and directory structure:

File and directory structure are a bit different if the JavaScript you’re working on is part of a larger website or web application versus a standalone JavaScript project. The overall directory structure is typically dictated by the server-side framework being used. Even though the overall directory structure may vary from project to project, you will undoubtedly have a subdirectory devoted just to JavaScript. This subdirectory may be called scripts or javascript, but there is almost always a single directory devoted to JavaScript files. Within that directory, there are a few common layouts.

One popular layout style is to have three primary directories in your JavaScript directory:

CSS Lint, a project that I manage, uses a variation of this approach. See Figure 13-1.

Figure 13-1. CSS Lint directory structure

For CSS Lint, the build directory is never checked in; however, the release directory always contains the most recent stable release. The src directory has several subdirectories, grouping related functionality together. The tests directory mirrors the directory structure of src, so the tests for src/core/CSSLint.js are found in tests/core/CSSLint.js.

jQuery uses a form of this layout as well. The only difference is that jQuery puts all of its source files directly into the src directory rather than having subdirectories for each. Subdirectories are reserved for extensions and resources for the core features. The test directory then contains files with the same name as the source file it’s testing. So src/ajax.js is tested by test/ajax.js (see Figure 13-2).

Figure 13-2. jQuery directory structure

Dojo uses a form similar to jQuery. The big difference with Dojo is that there is no top-level src directory. Instead, the top level contains source files as well as subdirectories for extensions and resources for core features. There is a top-level tests directory that mirrors the layout of the top-level directory itself, so date.js is tested by tests/date.js (see Figure 13-3).

Figure 13-3. Dojo directory structure

YUI 3 uses a modification of the original layout. Each subdirectory of src represents a single YUI module, and each module has at least four subdirectories:

Tests in YUI may be HTML files or JavaScript files, so exactly what’s contained in tests varies from module to module. Generally, there is at least one file named the same as the source file, so js/arraysort.js is tested by tests/arraysort.html or tests/arraysort.js. See Figure 13-4.

Figure 13-4. YUI 3 directory structure

Exactly which style of layout you choose will be largely based on your development and build process. It should be optimized to limit build time and make it easy for developers to know where new files should go.

Ant requires Java to run, so make sure that you have Java installed on your system. If you’re using Mac OS X, then Ant is already installed by default; for Ubuntu, run sudo apt-get install ant to install Ant. For other operating systems, following the instructions at http://ant.apache.org/manual/install.html.

The main build file for Ant is build.xml. When Ant runs on the command line, it looks for this file in the current directory, so it’s best to place build.xml in the root directory of your project. You needn’t keep all of the build-related information in this file, but build.xml must be present for Ant to work.

As you might expect, build.xml is an XML file containing instructions on how to perform the build. There are three basic parts of an Ant build system:

Each part of the build system is represented by an XML element. Here’s a sample build.xml file:

<project name="maintainablejs" default="hello">

    <target name="hello">
        <echo>Hello world!</echo>
    </target>

</project>

Every build.xml file begins with a <project> element representing the overall project. The name attribute is required and uniquely identifies this project. The default attribute specifies the default target to execute if no target is explicitly provided.

This file contains a single target, represented by the <target> element. The name attribute is also required here. The <echo> element represents the echo task, which outputs the enclosed text to the console. You can have any number of tasks in a target and any number of targets in a project.

Once you have a build.xml file, open a command prompt in that directory and type:

ant

By default, Ant will read the build.xml file and default attribute of <project> to determine which target to execute. If you were to run ant with the build.xml file from the previous example, it would execute the hello target. You can optionally specify which target to run right on the command line:

ant hello

When the target name is specified on the command line, Ant no longer uses the default target.

In both cases, you’ll see console output that looks like this:

Buildfile: /home/nicholas/tmp/build.xml

hello:
     [echo] Hello world!

BUILD SUCCESSFUL
Total time: 0 seconds

The output always shows you the build file being used as the first line. After that, you’ll see the target being executed followed by a list of tasks being executed. The task name is enclosed in square braces; any output is displayed to the right. You will also see a message in capital letters indicating whether the build was successful, followed by the amount of time the build took. These items are all helpful in determining the cause of build errors.

Each target may optionally be specified with dependencies—other targets that must be run and must succeed before the current target is executed. Dependencies are specified using the depends attribute, which is a comma-separated ordered list of targets to execute first. Here’s an example:

<project name="maintainablejs" default="hello">

    <target name="hello">
        <echo>Hello world!</echo>
    </target>

    <target name="goodbye" depends="hello">
        <echo>Goodbye!</echo>
    </target>

</project>

In this build.xml file, the target goodbye has a dependency on the target hello. Thus, running ant goodbye results in the following output:

Buildfile: /home/nicholas/tmp/build.xml

hello:
     [echo] Hello world!

goodbye:
     [echo] Goodbye!

BUILD SUCCESSFUL
Total time: 0 seconds

You can tell from the output that the hello target was executed before the goodbye target, and that both succeeded.

In most build files, there are a small number of targets that you’ll use frequently. The majority of targets are single steps that are designed to be used by rollup targets that execute multiple targets in a specific order.

Ant properties are similar to variables in JavaScript, as they are generic containers for data that can be changed and manipulated throughout execution of the build script. A property is defined using the <property> element:

<project name="maintainablejs">

    <property name="version" value="0.1.0" />

</project>

Each <property> element requires name and value attributes. You can later reference the property by using ${version}, such as:

Version is ${version}

When this Ant script is executed, the output is:

Buildfile: /home/nicholas/tmp/build.xml

version:
     [echo] Version is 0.1.0

BUILD SUCCESSFUL
Total time: 0 seconds

The special ${} syntax is used any time you want to insert a property value into task.

Properties can also be defined in a Java properties files and loaded directly into Ant. For instance, suppose you have a properties file named build.properties containing the following:

version = 0.1.0
copyright = Copyright 2012 Nicholas C. Zakas. All rights reserved.

You can import these properties into the Ant script by using the <loadproperties> element and specifying the filename with the srcfile attribute:

<?xml version="1.0" encoding=UTF-8"?>

<project name="maintainablejs" default="version">

    <property name="version" value="0.1.0" />

    <target name="version">
        <echo>Version is ${version}</echo>
    </target>

</project>

Properties loaded using <loadproperties> are accessible in the same manner as those defined explicitly within build.xml. For a large number of properties, or properties that need to be shared among multiple Ant scripts, it’s best to have them in a separate Java properties file.

At a minimum, it’s best to have several properties declared that can be used throughout your project, such as:

Throughout the rest of this book, you’ll see these properties used in Ant tasks. Be sure to define them appropriately in your project.

Buildr (https://github.com/nzakas/buildr) is a project that seeks to collect common frontend-related Ant tasks with easier syntax. A wide range of tools is available for working with JavaScript files, but they all work a bit differently. Buildr wraps all of these different tools in tasks that can be used in your Ant scripts.

To use Buildr, you must first get a copy of the source. Once you have the directory structure on your computer, you can import all of the tasks with this command:

<import file="/path/to/buildr/buildr.xml"/>

This command allows your build.xml file to make use of all the custom tasks defined in Buildr. The following chapters show you both how to create Ant tasks from scratch as well as how to use the Buildr tasks.

The first step in validating files is to locate the files. There are two different tasks for this purpose: <fileset> and <filelist>. The <fileset> task is used when you want to include a large number of files based on a pattern. Specify the dir attribute as the directory to look in and then includes with a filename pattern, such as:

<fileset dir="./src" includes="**/*.js" />

This fileset includes all JavaScript files contained in the src directory. You can optionally specify some file patterns to exclude as well:

<fileset dir="./src" includes="**/*.js" excludes="**/*-test.js />

This fileset includes all JavaScript files except the ones that end with -test.js. This is a common practice for excluding unit test files that are contained in the same directories as the source files.

The <filelist> task works similarly except that you must explicitly list the files to include. This task is best used when you want to retrieve references to a specific set of files. The <fileset> element also expects a dir for the directory. The files attribute contains a comma-separated list of files. For example:

<filelist dir="./src" files="core/core.js" />

In practice, you’ll end up using <fileset> more frequently than <filelist>, as it’s far more likely that you’ll be dealing with large groups of files rather than specific, named files.

The <apply> task is used to execute command-line utilities on a collection of files from within an Ant target. Because JSHint is written in JavaScript, you’ll need to use the Rhino command-line JavaScript engine to execute it. Download the latest Rhino release from http://www.mozilla.org/rhino and place the js.jar file in your dependencies folder (lib.dir).

To run JSHint on the command line, type the following:

java -jar js.jar jshint.js [options] [list of files]

For example:

java -jar js.jar jshint.js curly=true,noempty-true core/core.js

The <apply> task allows you to recreate command-line entires using the <arg> element. There are two ways to use <arg>: by specifying the path attribute for file or directory references, or by specifying the line attribute for plain text. You can break down the command-line format into the following pieces:

Given that, you can quickly create an Ant skeleton for this utility:

<target name="validate">       
  <apply executable="java">
    <arg line="-jar"/>
    <arg path="js.jar"/>
    <arg path="jshint.js" />        
    <arg 
     line="curly=true,forin=true,latedef=true,noempty=true,undef=true,rhino=false"
    />
    <arg path="core/core.js"/>
  </apply>        
</target>

Although this approach works, you should really run JSHint on a collection of JavaScript files rather than on a single one. The <apply> task makes this step easy by allowing you to specify a <fileset> and then include it in a particular spot on the command line by using the <srcfile> element. For example, the following target validates all JavaScript files in the source directory:

<target name="validate">       
  <apply executable="java">
    <fileset dir="${src.dir}" includes="**/*.js" />
    <arg line="-jar"/>
    <arg path="js.jar"/>
    <arg path="jshint.js" />        
    <arg 
     line="curly=true,forin=true,latedef=true,noempty=true,undef=true,rhino=false"
    />
    <srcfile/>
  </apply>
</target>

This Ant target now executes JSHint on every file specified by the <fileset> element. You can run the target via:

ant validate

Although the validate target works well, there are some improvements that can be made. First, the current version runs JSHint once on each file. So if there are three JavaScript files, it’s the equivalent of running this:

java -jar js.jar jshint.js curly=true,noempty-true first.js
java -jar js.jar jshint.js curly=true,noempty-true second.js
java -jar js.jar jshint.js curly=true,noempty-true third.js

There is some overhead when running java, specifically the creation and destruction of the Java Virtual Machine (JVM). This task adds a significant amount of time to the target.

The JSHint command-line script actually accepts multiple files, so it’s perfectly capable of using one JVM to check every file. Fortunately, the <apply> task makes it easy to pass in all of the filenames. You just need to set the parallel attribute to "true":

<target name="validate">       
  <apply executable="java" parallel="true">
    <fileset dir="${src.dir}" includes="**/*.js" />
    <arg line="-jar"/>
    <arg path="js.jar"/>
    <arg path="jshint.js" />        
    <arg 
     line="curly=true,forin=true,latedef=true,noempty=true,undef=true,rhino=false"
    />
    <srcfile/>
  </apply>
</target>

By adding one attribute, the validate target now passes all of the files onto the command line at once (separated by spaces). Doing so allows JSHint to read and validate all files with just one JVM and dramatically improves the target speed.

The last addition to the validate target is to have the build fail if validation fails. It’s usually a good idea to add this step, because it ensures that developers are aware of the problem. The current version of the validate target will output validation failures to the command line, but any other task that follows will continue to execute, potentially causing the failure messages to scroll off screen.

You can force <apply> to fail the build by setting the failonerror property to "true":

<target name="validate">       
  <apply executable="java" failonerror="true" parallel="true">
    <fileset dir="${src.dir}" includes="**/*.js" />
    <arg line="-jar"/>
    <arg path="js.jar"/>
    <arg path="jshint.js" />        
    <arg 
     line="curly=true,forin=true,latedef=true,noempty=true,undef=true,rhino=false" 
    />
    <srcfile/>
  </apply>
</target>

This version of the validate target will fail the build when an error occurs during execution of <apply>. An error is any nonzero exit code returned from the executable. Because JSHint returns 1 when a validation error occurs, it will cause the build to fail.

The last step in improving the validate task is to externalize three pieces of data:

As these may change in the future, it’s best to represent them as properties and include them in your properties file or at the top of your build.xml file. Here’s an example properties file:

src.dir = ./src
lib.dir = ./lib

rhino = ${lib.dir}/js.jar
jshint = ${lib.dir}/jshint.js

jshint.options = curly=true,forin=true,latedef=true,noempty=true,undef=true\
,rhino=false

You can then reference the properties from the validate target:

<target name="validate">       
    <apply executable="java" failonerror="true" parallel="true">
        <fileset dir="${src.dir}" includes="**/*.js" />
        <arg line="-jar"/>
        <arg path="${rhino}"/>
        <arg path="${jshint}" />        
        <arg line="${jshint.options}" />
        <srcfile/>
    </apply>
</target>

With this change, you’re easily able to update the location of files and JSHint options without needing to go back into the target.

Buildr has a <jshint> task that abstracts away a lot of the configuration necessary to run JSHint. After importing the buildr.xml file as mentioned in the previous chapter, use the <jshint> task by passing in any number of <fileset> elements:

<target name="validate">
    <jshint>
        <fileset dir="${src.dir}" includes="**/*.js" />
    </jshint>
</target>

You can also change the default options by using the options attribute:

<target name="validate">
    <jshint options="${jshint.options}">
        <fileset dir="${src.dir}" includes="**/*.js" />
    </jshint>
</target>

The end result is exactly the same as using the target from the previous section.

The <concat> task is one of the simplest in Ant. You simply specify a destfile attribute containing the destination filename and then include as many <fileset> and <filelist> elements as you want. At it’s simplest, you can have a target such as:

<target name="concatenate">

    <concat destfile="${build.dir}/build.js">
        <fileset dir="${src.dir}" includes="**/*.js" />
    </concat>

</target>

This target concatenates all JavaScript files in the source directory into a single file called build.js in the build directory. Keep in mind that the files are concatenated in the order in which they appear on the filesystem (alphabetically). If you want a more specific ordering, you’ll need to specify it explicitly, such as:

<target name="concatenate">

    <concat destfile="${build.dir}/build.js">
        <filelist dir="${src.dir}" files="first.js,second.js" />
        <fileset dir="${src.dir}" includes="**/*.js" excludes="first.js,second.js"/>
    </concat>

</target>

This version of the target ensures that first.js is the first file added to the final file and second.js comes right after that. Remember, you can use any number of <fileset> and <filelist> elements, so you can concatenate in any order you can imagine.

Concatenating files together comes with a series of challenges. One of the trickiest issues is dealing with the last line of a file. If a file doesn’t have a newline character on its last line, then concatenating that file with another may result in broken syntax. By setting fixlastline attribute to "yes", the <concat> task will automatically add a newline character to the last line if one doesn’t already exist:

<target name="concatenate">

    <concat destfile="${build.dir}/build.js" fixlastline="yes">
        <filelist dir="${src.dir}" files="first.js,second.js" />
        <fileset dir="${src.dir}" includes="**/*.js" excludes="first.js,second.js"/>
    </concat>

</target>

It’s a good idea to always set fixlastline to "yes" for JavaScript, as newlines are valid end-of-statement tokens.

Fixing the last line is useful, but how do you know which end-of-line marker is used? If your source files are being edited by people on different operating systems, you may want to ensure consistency in the built files. The <concat> task has an optional eol attribute that specifies which end-of-line markers to use. The default value is the default for the system ("crlf" for Windows, "lf" for Unix, and "cr" for Mac OS X). You can choose any one of these values, and all of the line endings in the concatenated file will automatically be switched to that format:

<target name="concatenate">

    <concat destfile="${build.dir}/build.js" fixlastline="yes" eol="lf">
        <filelist dir="${src.dir}" files="first.js,second.js" />
        <fileset dir="${src.dir}" includes="**/*.js" excludes="first.js,second.js"/>
    </concat>

</target>

This target changes all end-of-line markers to Unix style, which is the recommended format for JavaScript files, as it has the greatest cross-platform compatibility (and because most web servers run on a Unix variant).

The <concat> task also has the handy ability to prepend and append plain text to the resulting file. This capability allows you to insert pieces of information into the file that you might otherwise not have available. For instance, I tend to insert the build time into files so I can more easily track down errors. To do so, I start by defining a <tstamp> element at the top of the file:

<tstamp>
  <format property="build.time"
          pattern="MMMM d, yyyy hh:mm:ss"
          locale="en,US"/>
</tstamp>

This code creates a new timestamp when the build.xml file is executed by Ant. The resulting date string is stored in a property named build.time. The pattern attribute is a date-time formatting string. I can then use the <header> element to add this information into the built file:

<target name="concatenate">

    <concat destfile="${build.dir}/build.js" fixlastline="yes" eol="lf">
        <header>/* Build Time: ${build.time} */</header>
        <filelist dir="${src.dir}" files="first.js,second.js" />
        <fileset dir="${src.dir}" includes="**/*.js" excludes="first.js,second.js"/>
    </concat>

</target>

This new version of the concatenate target inserts a comment at the top of the file containing the build time. The resulting first line of the file has this format:

/* Build Time: May 25, 2012 03:20:45 */

There is also a <footer> element that can be used to add additional text at the bottom of the file. For example, this version of concatenate puts the build time at the bottom:

<target name="concatenate">

    <concat destfile="${build.dir}/build.js" fixlastline="yes" eol="lf">
        <filelist dir="${src.dir}" files="first.js,second.js" />
        <fileset dir="${src.dir}" includes="**/*.js" excludes="first.js,second.js"/>
        <footer>/* Build Time: ${build.time} */</footer>            
    </concat>

</target>

You can use both <header> and <footer> at the same time or just one at a time.

Baking refers to the final touches you put into files before considering them ready for deployment. A lot of times, this step involves either adding additional text into a file or replacing existing text with something else. Inserting the build time, as in the previous example, is a type of baking. Other common tasks are automatically including license information and inserting version information. Both can be done very easily using Ant.

Many projects have a license file included somewhere in source control. The license file is separate because it may change independently of the code. It’s useful to automatically insert the license information at the top of files before pushing them to production. You could potentially insert the license file using a <filelist> element, but that would mean that the license file must be in a property comment format for JavaScript. It’s much easier to let the license file be plain text and add the comments around it. You can load text from any file using the <loadfile> task:

<loadfile property="license" srcfile="license.txt" />

This code loads text from license.txt and stores it in a property named license. Once it’s in a property, you can use the <header> element to insert the text as a comment:

<target name="concatenate">

    <loadfile property="license" srcfile="license.txt" />

    <concat destfile="${build.dir}/build.js" fixlastline="yes" eol="lf">
        <header trimleading="yes">/*!
        ${license}
        */
        /* Build time: ${build.time} */
        </header>
        <filelist dir="${src.dir}" files="first.js,second.js" />
        <fileset dir="${src.dir}" includes="**/*.js" excludes="first.js,second.js"/>
    </concat>

</target>

The license is inserted with a multiline JavaScript comment that has an exclamation point as the first character, which tells code minifiers (see Chapter 17) that the comment is important and should not be removed. The <header> element also has trimleading set to "yes". This attribute specifies that leading white space on each line inside of <header> should be removed. That way, all text is aligned at the first column in the final file.

The other part of baking, replacing some text within files, is accomplished quite easily using the <replaceregexp> task. This task systematically goes through any number of files and uses regular expressions to replace values. As an example, I tend to use the token @VERSION@ in my source files to indicate where the version number should be inserted. For instance, you might have this in a JavaScript file:

var MyProject = {
    version: "@VERSION@"
};

You can replace @VERSION@ with an actual version number using the following:

<replaceregexp match="@VERSION@" replace="${version}" flags="g" byline="true">
    <fileset dir="${build.dir}" includes="**/*"/>
</replaceregexp>

The <replaceregexp> task takes the regular expression from the match attribute and replaces it with the text in the replace attribute. Regular expression flags such as g, i, and m are specified using the flags attribute, and byline indicates whether the regular expression should match just a single line. You then specify any number of files in which this replacement should be made.

Because <replaceregexp> doesn’t create new files, be sure to run it on the built files, as in the following example:

<target name="concatenate">

    <concat destfile="${build.dir}/build.js" fixlastline="yes" eol="lf">
        <filelist dir="${src.dir}" files="first.js,second.js" />
        <fileset dir="${src.dir}" includes="**/*.js" excludes="first.js,second.js"/>
        <footer>/* Build Time: ${build.time} */</footer>            
    </concat>

    <replaceregexp match="@VERSION@" replace="${version}" flags="g" byline="true">
        <fileset dir="${build.dir}" includes="**/*"/>
    </replaceregexp>

</target>

This code replaces all instances of @VERSION@ in all built files with the version property. Although the replacement takes place in the concatenate target here, you may also want to have a separate target for baking, such as:

<target name="bake">

    <replaceregexp match="@VERSION@" replace="${version}" flags="g" byline="true">
        <fileset dir="${build.dir}" includes="**/*"/>
    </replaceregexp>

</target>

Separating out the baking step makes sense when it doesn’t involve the <concat> task and may not always be done as part of the build process.

Minifying a JavaScript file isn’t very complicated, but mistakes or invalid syntax can result if you use an unsafe process. For this reason, it’s best to use a minifier that actually parses the JavaScript before making changes. Parsers know what valid syntax is and can more easily create valid syntax. The three most popular parsing minifiers are:

Exactly which minifier to use is a matter of preference. Some prefer YUI Compressor because of its focus on ensuring that the resulting code doesn’t contain errors and its simple optimizations. Others prefer Closure Compiler because it tends to produce files that are smaller than YUI Compressor. Still others prefer UglifyJS because it doesn’t rely on Java and produces fewer syntax errors than Closure Compiler while also producing the smallest possible result.

src.dir = ./src
lib.dir = ./lib

yuicompressor = ${lib.dir}/yuicompressor.jar

yuicompressor.options = --preserve-semi

java -jar yuicompressor.jar [options] [file] -o [outputfile]

java -jar yuicompressor.jar --preserve-semi core/core.js -o core/core-min.js

<target name="minify">

    <apply executable="java" failonerror="true">

        <fileset dir="${build.dir}" includes="*.js"/>
        <mapper type="glob" from="*.js" to="${build.dir}/*-min.js"/>

        <arg line="-jar"/>
        <arg path="${yuicompressor}"/>
        <arg line="${yuicompressor.options}"/>
        <srcfile/>

        <arg line="-o"/>           
        <targetfile/>
    </apply>     

</target>

<target name="minify">
    <yuicompressor outputdir="${build.dir}" preserve-semi="true">
        <fileset dir="${build.dir}" includes="*.js" />
    </yuicompressor>
</target>

src.dir = ./src
lib.dir = ./lib

closure = ${lib.dir}/compiler.jar

closure.options = --compilation_level SIMPLE_OPTIMIZATIONS

java -jar compiler.jar [options] --js [file] --js_output_file [outputfile]

java -jar compiler.jar --compilation_level SIMPLE_OPTIMIZATIONS --js core/core.js 
    --js_output_file core/core-min.js

<target name="minify">

    <apply executable="java" failonerror="true">

        <fileset dir="${build.dir}" includes="*.js"/>
        <mapper type="glob" from="*.js" to="${build.dir}/*-min.js"/>

        <arg line="-jar"/>
        <arg path="${closure}"/>
        <arg line="${closure.options}"/>

        <arg line="--js"/>
        <srcfile/>

        <arg line="--js_output_file"/>            
        <targetfile/>
    </apply>     

</target>

<target name="minify">
    <closure outputdir="${build.dir}" compilation-level="SIMPLE_OPTIMIZATIONS">
        <fileset dir="${build.dir}" includes="*.js" />
    </closure>
</target>

sudo npm install -g uglify-js

uglifyjs [options] -o [outputfile] [file]

uglifyjs --no-mangle-functions -o core/core-min.js core/core.js

src.dir = ./src
lib.dir = ./lib

uglifyjs = uglifyjs

uglifyjs.options = --no-mangle-functions

<target name="minify">

    <apply executable="uglifyjs" failonerror="true">

        <fileset dir="${build.dir}" includes="*.js"/>
        <mapper type="glob" from="*.js" to="${build.dir}/*-min.js"/>

        <arg line="${ugilfyjs.options}"/>

        <arg line="-o"/>           
        <targetfile/>
        <srcfile/>
    </apply>     

</target>

<target name="minify">
    <uglifyjs outputdir="${build.dir}" no-mangle-functions="true">
        <fileset dir="${build.dir}" includes="*.js" />
    </uglifyjs>
</target>

Minification of JavaScript files is the first step before deployment. The second is to compress the files to be as small as possible during transmission. The minifiers mentioned in this chapter don’t perform compression on JavaScript (even YUI Compressor only performs minification). Compression usually happens later in the process, either at runtime using HTTP compression on the web server or during build time.

Accept-Encoding: gzip, deflate

Content-Encoding: gzip

<gzip src="${build.dir}/build.js" destfile="${build.dir}/build.js.gz"/>

<target name="compress">

    <gzip src="${build.dir}/build.js" destfile="${build.dir}/build.js.gz"/>

</target>

<script language="javascript"><![CDATA[

    // code here

]]></script>

<target name="compress">

    <!-- store filenames in a property delimited by ; -->
    <pathconvert pathsep=";" property="compress.jsfiles">
        <fileset dir="${build.dir}" includes="*.js"/>
    </pathconvert>    

    <script language="javascript"><![CDATA[

        importPackage(java.io);

        <!-- get the property and convert to an array-->
        var files = project.getProperty("compress.jsfiles").split(";"),
            gzip,
            i,
            len;

        for (i=0, len=files.length; i < len; i++) {

            // create new gzip task
            gzip = project.createTask("gzip");
            gzip.setSrc(new File(files[i]));
            gzip.setDestfile(new File(files[i].replace(".js", ".js.gz")));
            gzip.perform();
        }

    ]]> </script>    
</target>

<target name="compress">
    <gzipall>
        <fileset dir="${build.dir}" includes="*-min.js" />
    </gzipall>
</target>

JSDoc Toolkit is perhaps the most commonly used JavaScript documentation generator. An evolution of the original JSDoc released in 2011, JSDoc Toolkit is used by Google and SproutCore and is often credited with starting the trend of writing JavaScript-specific documentation generators. It uses the same basic syntax as Javadoc, with special multiline comments indicating documentation information. For example:

/**
 * @namespace The main application object.
 */
var MyApplication = {

    /**
     * Adds two numbers together.
     * @param {int} num1 The first number.
     * @param {int} num2 The second number.
     * @returns {int} The sum of the two numbers.
     * @static
     */
    add: function (num1, num2) {
        return num1 + num2;
    }
}

Any object for which there is no constructor to call is considered a namespace in JSDoc. So MyApplication is a namespace and is indicated as such by the @namespace tag followed by the description. The method MyApplication.add() has two parameters, specified by @param and followed by the expected data type, the parameter name, and the description. The method returns a result, so the @return tag indicates the expected data type and describes the return value. The @static tag indicates that the method doesn’t require instantiation of an object to be used.

When JSDoc Toolkit processes JavaScript files, it looks both at the JavaScript code and at the documentation comments to create HTML-based documentation. For full syntax information, see http://code.google.com/p/jsdoc-toolkit/w/list.

JSDoc Toolkit is written almost entirely in JavaScript and uses a custom Rhino launcher JAR file (jsrun.jar) to execute:

java -jar jsrun.jar app/run.js [file]+ -t=[templates] -d=[directory] [options]

The app/run.js file is the main executable for JSDoc toolkit. You can pass in as many JavaScript files as you’d like to document. The -t flag specifies the templates to use (by default, you can use the ones that come with JSDoc Toolkit) and -d specifies the output directory. For example:

java -jar jsrun.jar app/run.js core/core.js -t=templates/jsdoc/ -d=./out

This command creates documentation for core/core.js using the templates in templates/jsdoc/ and outputs the final HTML documentation to the out directory. Because you need to use the JSDoc Toolkit directory several times (for jsrun.jar, app/run.js, and the default templates), it’s best to keep this information in properties, as in the following:

src.dir = ./src
lib.dir = ./lib

jsdoc.dir = ${lib.dir}/jsdoc-toolkit
jsdoc = ${jsdoc.dir}/jsrun.jar
jsdoc.run = ${jsdoc.dir}/app/run.js
jsdoc.templates = ${jsdoc.dir}/templates
jsdoc.output = ./docs

The target for generating documentation is as follows:

<target name="document">       
    <apply executable="java" failonerror="true" parallel="true">
        <fileset dir="${src.dir}" includes="**/*.js" />
        <arg line="-jar"/>
        <arg path="${jsdoc}"/>
        <arg path="${jsdoc.run}" />
        <arg line="-t=${jsdoc.templates}" />
        <arg line="-d=${jsdoc.output}" />
        <srcfile/>
    </apply>
</target>

Because the built files have all comments stripped, the document target generates documentation on the source files instead. Similar to the validate target, the <apply> task has parallel set to "true" so that all of the files are passed on the command line at once. The rest are just <arg> elements specifying the different options. By default, the documentation is generated into a top-level docs directory, but you may want to change that location based on your directory structure.

The Buildr task for JSDoc is <jsdoc> and has a required outputdir attribute. There is also a templates attribute that is optional (if you don’t want to use the default). For example:

<target name="document">       
    <jsdoc outputdir="${jsdoc.output}">
        <fileset dir="${src.dir}" includes="**/*.js" />
    </jsdoc>
</target>

This target functions the same as the previous version but is a bit more obvious about what it’s doing.

The original version of YUI Doc was written in Python and was used by the YUI library for several years. More recently, a new JavaScript version was created that understands the same syntax. This is the tool that generates the documentation on http://yuilibrary.com. The syntax is very similar to JSDoc, as it is based off of Javadoc-style comments. The biggest difference is that YUI Doc requires you to name your properties and methods in the documentation comment, whereas JSDoc is able to infer the name from looking at the JavaScript code. For example:

/**
 * The main application object.
 * @class MyApplication
 * @static
 */
var MyApplication = {

    /**
     * Adds two numbers together.
     * @param {int} num1 The first number.
     * @param {int} num2 The second number.
     * @returns {int} The sum of the two numbers.
     * @method add
     */
    add: function (num1, num2) {
        return num1 + num2;
    }
}

In YUI Doc terms, MyApplication is a class even though it has no constructor. The class description is the first line, and @class MyApplication identifies the object as a class. Because there is no constructor, the @static tag indicates that MyApplication is an object and all of its methods are accessed statically. The MyApplication.add() method has syntax that’s very similar to JSDoc, with the main difference being the @method tag indicating the method name.

YUI Doc is written in JavaScript and runs on Node.js. It can be installed using npm via:

sudo npm install -g yuidoc

The command line for YUI Doc is simpler than that of JSDoc:

yuidoc [options] [directory]+ -o [directory]

For example:

yuidoc ./src -o ./docs

This command recursively goes through the src directory and parses all JavaScript files it finds. The generated HTML documentation ends up in the docs directory. Even though there are command-line options for YUI Doc, they aren’t necessary in order to get up and running. The properties for YUI Doc are simple:

src.dir = ./src
lib.dir = ./lib

yuidoc = yuidoc
yuidoc.output = ./docs

You may be wondering what the value of having yuidoc = yuidoc is, as it’s redundant. It’s always best to keep application paths as properties, because paths and filenames have a tendency to change over time. Even though these are identical now, there’s no telling if this will remain true in the future. When things change, you want to be able to make a quick change to the properties file rather than going through the build.xml to find where the executable is set.

Because YUI Doc expects one or more directories to be passed in instead of files, the target becomes very simple when there’s just one source directory:

<target name="document">       
    <exec executable="yuidoc" failonerror="true">
        <arg path="${src.dir}"/>
        <arg line="-o" />
        <arg path="${yuidoc.output}"/>
    </exec>
</target>

This target uses <exec> instead of <apply>, because there is only a single directory being passed in. The <exec> task functions similarly to <apply>, except that it doesn’t require a <srcfile> element. The <arg> elements construct the full command line.

The Buildr <yuidoc> task encapsulates this functionality and has two required attributes, inputdir and outputdir, to specify where the JavaScript files are and where the documentation should be generated, respectively. For example:

<target name="document">
    <yuidoc inputdir="${src.dir}" outputdir="${yuidoc.output}"/>
</target>

The <yuidoc> task assumes that you have YUI Doc installed already.

YUI Test is the unit testing framework for the YUI Library. The most recent version of YUI Test is more than a simple testing library. In addition to removing dependencies on the core YUI library, YUI Test supports a suite of utilities to aid JavaScript testing. One of these tools is called the YUI Test Selenium Driver and is designed to work with Selenium to enable easy browser testing.

Selenium is a server that is capable of launching browsers and running commands inside of them. Originally intended for use by QA engineers writing functional tests, Selenium gained popularity for JavaScript testing due to the ease with which it interacts with browsers.

java -jar selenium-server-standalone-x.y.z.jar

<!DOCTYPE html>
<html>
<head>
    <title>YUI Test</title>

    <!-- include YUI Test library -->
    <script src="yuitest.js"></script>

    <!-- include your test files -->
    <script src="tests1.js"></script>
    <script src="tests2.js"></script>
</head>
<body>
    <script>
        YUITest.TestRunner.run();
    </script>
</body>
</html>

java -jar yuitest-selenium-driver.jar [options] [url]+

java -jar yuitest-selenium-driver.jar http://www.example.com/tests.html

java -jar yuitest-selenium-driver.jar --host testing.example.com 
    --port 9000 http://www.example.com/tests.html

java -jar yuitest-selenium-driver.jar 
    --browsers *firefox,*iexplore http://www.example.com/tests.html

<?xml version="1.0"?>
<yuitest>
    <tests base="http://www.example.com/tests/" timeout="10000">
        <url>test_core</url>
        <url timeout="30000">test_util</url>
        <url>test_ui</url>
    </tests>
</yuitest>

java -jar yuitest-selenium-driver.jar --tests tests.xml

src.dir = ./src
lib.dir = ./lib
tests.dir = ./tests

yuitestselenium = ${lib.dir}/yuitest-selenium-driver.jar

yuitestselenium.host = testing.example.com
yuitestselenium.port = 4444
yuitestselenium.tests = ${tests.dir}/tests.xml
yuitestselenium.browsers = *firefox

<target name="test">

    <exec executable="java" failonerror="true">
        <arg line="-jar"/>
        <arg path="${yuitestselenium}"/>
        <arg line="--host ${yuitestselenium.host}"/>
        <arg line="--port ${yuitestselenium.port}"/>
        <arg line="--browsers ${yuitestselenium.browsers}"/>
        <arg line="--tests ${yuitestselenium.tests}"/>
        <arg line="--erroronfail"/>
    </exec>     

</target>

<target name="test">

    <yuitest-selenium host="${yuitestselenium.host}" 
        port="${yuitestselenium.port}" browsers="${yuitestselenium.browsers}"
        tests="${yuitestselenium.tests}"/>

</target>

Yeti is another tool designed to work with YUI Test. Unlike the YUI Test Selenium Driver, Yeti is a completely standalone solution written in JavaScript that runs on Node.js. Yeti requires you to have an HTML file that automatically executes your tests, so you can use the same HTML files that are used with the YUI Test Selenium Driver.

You can install Yeti via npm with:

sudo npm install -g yeti

Running Yeti is simply a matter of passing in the HTML file on the command line:

yeti test.html

This command runs all of the tests on Firefox or Safari by default (depending on platform) and outputs the result to the command line. If a Yeti server is running locally, then this command also runs tests on all connected browsers and reports all results.

Due to the simplicity of Yeti, the Ant target requires very little configuration in a properties file:

src.dir = ./src
lib.dir = ./lib
tests.dir = ./tests

yeti = yeti

And the Ant target itself is very straightforward as well:

<target name="test">

    <apply executable="yeti" failonerror="true" parallel="true">
        <fileset dir="${tests.dir}" includes="**/*.html" />
        <srcfile/>
    </apply>

</target>

The test target uses the <apply> task to pass all HTML files found in the tests directory to Yeti. The results are output on the screen, and the build will fail if there are errors.

The Buildr <yeti> task makes using Yeti even simpler:

<target name="test">

    <yeti>
        <fileset dir="${tests.dir}" includes="**/*.html" />
    </yeti>

</target>

Keep in mind that the <yeti> task requires you to have Yeti already installed on the computer that is executing the build script.

PhantomJS is a headless version of WebKit, the rendering engine that powers Safari and Chrome. As such, it acts very similarly to these browsers (though not exactly the same) and allows you to perform true browser testing without actually opening a browser. PhantomJS comes with scripts to run tests in two different JavaScript testing frameworks: Jasmine and QUnit.

PhantomJS isn’t just a browser—it’s also a scripting environment for that browser. The scripts to run Jasmine and QUnit are part of a suite of scripts that ships with PhantomJS. Both scripts require you to use the appropriate HTML page template for the framework being used.

$ sudo add-apt-repository ppa:jerome-etienne/neoip
$ sudo apt-get update
$ sudo apt-get install phantomjs

brew install phantomjs

phantomjs [driver] [HTML file]

phantomjs examples/run-qunit.js tests.html

phantomjs examples/run-jasmine.js tests.html

src.dir = ./src
lib.dir = ./lib
tests.dir = ./tests

phantomjs = phantomjs
phantomjs.driver = ${lib.dir}/phantomjs/examples/run-qunit.js
phantomjs.tests = tests.html

<target name="test">

    <exec executable="phantomjs" failonerror="true">
        <arg path="${phantomjs.driver}"/>
        <arg path="${tests.dir}/${phantomjs.tests}"/>
    </exec>

</target>

<target name="test">

    <phantomjs driver="${phantomjs.driver}">
        <fileset dir="${tests.dir}" includes="*.html" />
    </phantomjs>

</target>

JsTestDriver is a command-line utility written by engineers at Google. Similar to Selenium and Yeti, JsTestDriver works with already installed browsers to run tests. JsTestDriver has its own JavaScript testing framework as well, so you must write tests using that library by default. There is a QUnit adapter to allow QUnit-based tests to be executed with JsTestDriver, and it’s possible to write your own adapter if you so choose.

server: http://localhost:4224

load:
    - tests/*.js

java -jar JsTestDriver.jar --port [port] --browser [browsers] --config [file] 
    --tests all --testOutput [directory]

java -jar JsTestDriver.jar --port 4224 --browser firefox,iexplore 
    --config conf/conf.yml --tests all --testOutput ./results

src.dir = ./src
lib.dir = ./lib
tests.dir = ./tests

jstestdriver = ${lib.dir}/JsTestDriver.jar
jstestdriver.port = 4224
jstestdriver.browser = firefox,iexplore
jstestdriver.config = conf/conf.yml
jstestdriver.output = ./results

<target name="test">

    <exec executable="java" failonerror="true">
        <arg line="-jar"/>
        <arg path="${jstestdriver}"/>
        <arg line="--port ${jstestdriver.port}"/>
        <arg line="--browser ${jstestdriver.browser}"/>
        <arg line="--conf"/>
        <arg path="${jstestdriver.config}"/>
        <arg line="--tests all"/>
        <arg line="--testOutput"/>
        <arg path="${jstestdriver.output}"/>
    </exec>     

</target>

   <target name="test">
    
        <jstestdriver config="${jstestdriver.config}" 
            outputdir="${jstestdriver.output}"
            tests="all" port="${jstestdriver.port}" 
            browser="${jstestdriver.browser}"/>
   
    </target>

Before putting together the build system, there are a couple of small steps that are missing. The first is the creation of the build directory. As this directory is transient (and won’t be checked in), the build system is responsible for its creation. The <mkdir> Ant task handles this easily:

<target name="init">
    <mkdir dir="${build.dir}"/>
</target>

The init target just does one thing: create the build directory so all the built files have a place to be put. It’s possible that other tasks, such as <concat>, may end up making this directory if it doesn’t already exist. However, it’s best to explicitly state each step of the build process to ensure that reordering of tasks or targets doesn’t cause errors.

The second missing piece is the cleanup of the build directory. In between builds, you want to remove all files and start over from scratch. The fastest way to do that is simply to delete the build directory using the <delete> task:

<target name="clean">
    <delete dir="${build.dir}"/>
</target>

The clean target removes the build directory so you’re certain to get the latest files.

To put the build system pieces together in the correct order, it helps to think about your development process and the different build types you’ll need. It’s very rare for a project to have a single build type and much more common for there to be at least three:

Of course, your project have many more build types depending on your development process.

Your build.xml should always start out looking like this:

<project name="yourapp" default="build.dev">

    <!-- import properties -->
    <loadproperties srcfile="yourapp.properties" />

    <!-- define or import utility targets here -->

    <!-- initialization and cleanup -->
    <target name="init">
        <mkdir dir="${build.dir}"/>
    </target>

    <target name="clean">
        <delete dir="${build.dir}"/>
    </target>

    <!-- main builds -->
    <target name="build.dev">    
    </target>

    <target name="build.int">    
    </target>

    <target name="build.release">    
    </target>

</project>

Make sure to begin by importing the properties file(s) to get all of the data needed for the targets. Then, either include or import the utility targets such as those created in the preceding build system chapters. Sometimes it helps to keep the utility targets in one or more separate XML files, but ultimately it’s up to you. After that, the init and clean targets round out the utility targets. The final section contains targets for each build type.

<project name="yourapp" default="build.dev">

    <!-- omitted for clarity -->

    <!-- main builds -->
    <target name="build.dev" depends="clean,init,validate,concatenate">    
    </target>

</project>

<project name="yourapp" default="build.dev">

    <!-- omitted for clarity -->

    <!-- main builds -->
    <target name="build.int depends="build.dev,minify,test,document">    
    </target>

</project>

<project name="yourapp" default="build.dev">

    <!-- omitted for clarity -->

    <!-- main builds -->
    <target name="build.release" depends="build.int,bake">    
    </target>

</project>

Just using a build system is a good first step in creating a maintainable project. The next step is to integrate your build system into a CI system. CI systems run builds automatically based on certain actions or regular intervals. For instance, you might run a build once an hour to get all of the latest checked-in files deployed to an integration environment. If that fails, it may send emails to the developers asking them to fix any issues. Having a CI system is an important part of any good software project. Fortunately, there are some excellent free resources for CI.

Jenkins

Jenkins is one of the most widely used CI systems. It is a Java-based web application that is designed for managing multiple builds. It integrates with several source control repositories by default and can support almost any others through an extensive plugin library. Jenkins works natively with Ant as well as shell scripts, meaning that you can reuse any existing build scripts with Jenkins.

Setting up Jenkins is quite easy; just download the latest WAR file and start it:

java -jar jenkins.war

Jenkins starts up a web server accessible at http://localhost:8080/. Navigate to that location in your web browser, and you’re ready to start creating build jobs.

A job is a collection of build steps to execute. Click the “New Job” link to create your first job. The next page asks you to select which type of job you’d like to create. If you’re just using Ant for your build system, then select “Build a free-style software project.” After creating the new job, you’re taken to a configuration page.

There are some basic options on the configuration page, but the really interesting parts start lower on the page, with the section called “Build Triggers.” This is where you decide how frequently the build should run. It can be triggered after another build finishes, on a timed schedule, or based on check-ins to source control. For your primary integration build, you’ll probably want to kick off the build based on check-ins, so the last option works well. “Poll SCM” means that Jenkins will poll your source control system (as specified in the previous section). The poll format is the same as setting up a cron job on a Linux system, so @hourly works for checking source control each hour (see Figure 20-1).

Figure 20-1. Jenkins build triggers

Next, you set up the job to execute one or more Ant targets. To do so, click the “Add Build Step” button to display a drop-down menu of options. Select “Invoke Ant.” A new build step appears in the page asking you to specify the Ant targets to execute (see Figure 20-2).

Figure 20-2. Adding an Ant build step

If you’re using Jenkins with source control, it will automatically find the build.xml file in your root directory, so you need specify only the Ant target name. If you’re setting up the integration build, for example, then enter build.int into the textbox as in Figure 20-3.

Figure 20-3. Specifying an Ant target

If you’re not using a build.xml file in the project root, or not using Jenkins with source control, then click on the “Advanced” button and you can specify the path to your build.xml file manually.

After that, you can specify to send an email when the build fails. Jenkins allows you to specify the email address that should always be used for this notification, as well as for sending emails to the committers who broke the build (using source control to retrieve the email address). It’s a good idea to always send an email when the build didn’t succeed (see Figure 20-4).

Figure 20-4. Configuring email notifications

Once you’re done setting up email notifications, click “Save” at the bottom of the page to save the build job. Your build job will now execute once an hour; however, you can manually run the build at any time by going to Jenkins and clicking the “Build Now” link.

This is just a brief introduction to Jenkins and the power of continuous integration. There are many, many more things you can do with Jenkins, such as tracking the results of unit tests, publishing build logs, setting up dependent builds, and more. The Jenkins website is a great resource for learning more about the various options available.