Table of Contents for

Maintainable JavaScript

One of the worst practices in JavaScript is overriding a method on an object you don’t own, which is precisely what caused us problems when I worked on the My Yahoo! team. Unfortunately, JavaScript makes it incredibly easy to override an existing method. Even the most venerable of methods, document.getElementById(), can be easily overridden:

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

There is absolutely nothing preventing you from overwriting DOM methods as in this example. What’s worse, any script on the page is capable of overwriting any other script’s methods. So any script could override document.getElementById() to always return null, which in turn would cause JavaScript libraries and other code that relies upon this method to fail. You’ve also completely lost the original functionality and can’t get it back.

You may also see a pattern like this:

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

In this example, a pointer to the original document.getElementById() is stored in document._originalGetElementById() so that it can be used later. Then, document.getElementById() is overridden to contain a new method. That new method may call the original in some cases, but in one case, it won’t. This override-plus-fallback pattern is at least as bad as the original, and perhaps worse because sometimes document.getElementById() behaves as expected and sometimes it doesn’t.

I have firsthand experience dealing with the fallout after someone overrides an existing object method. It occurred while I was working on the My Yahoo! team, because someone had overridden the YUI 2 YAHOO.util.Event.stopEvent() method to do something else. It took days to track this problem down, because we all assumed that this method was doing exactly what it always did, so we never traced into that method once we hit it in a debugger. Once we discovered the overridden method, we also found other bugs, because the same method was being used in other places with its original intended usage—but of course it wasn’t behaving in that way. Unraveling this was an incredible mess, one that cost a lot of time and money on a big project.

It’s quite easy to add new methods to existing objects in JavaScript. You need only assign a function onto an existing object to make it a method, which allows you to modify all kinds of objects:

// 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
};

There is little stopping you from adding methods to any object you come across. The big problem with adding methods to objects you don’t own is that you may end up with a naming collision. Just because an object doesn’t have a method right now doesn’t mean it won’t in the future. What’s worse is that if the future native method behaves differently than your method, then you have a maintenance nightmare.

Take a lesson from the history of the Prototype JavaScript library. Prototype was famous for modifying all kinds of JavaScript objects. It added methods to DOM and native objects at will; in fact, most of the library was defined as extensions to existing objects rather than by creating their own. The Prototype developers saw the library as a way of filling in JavaScript’s gaps. Prior to version 1.6, Prototype implemented a method called document.getElementsByClassName(). You may recognize this method, because it was officially defined in HTML5 to standardize Prototype’s approach.

Prototype’s document.getElementsByClassName() method returned an array of elements containing the specified CSS classes. Prototype also had added a method on arrays, Array.prototype.each(), which iterated over the array and executed a function on each item. This led to developers writing code such as:

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

This code didn’t have a problem until HTML5 standardized the method and browsers began implementing it natively. The Prototype team knew the native document.getElementsByClassName() was coming, so they did some defensive coding similar to the following:

if (!document.getElementsByClassName) {

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

}

So Prototype was defining document.getElementsByClassName() only if it didn’t already exist. That would have been the end of the issue except for one important fact. The HTML5 document.getElementsByClassName() didn’t return an array, so the each() method didn’t exist. Native DOM methods use a specialized collection type called NodeList, and document.getElementsByClassname() returned a NodeList to match the other DOM methods.

Because NodeList doesn’t have an each() method, either natively or added by Prototype, using each() caused a JavaScript error when executed in browsers that had a native implementation of document.getElementsByClassName(). The end result was that users of Prototype had to upgrade both the library code and their own code—quite the maintenance nightmare.

Learn from Prototype’s mistake. You cannot accurately predict how JavaScript will change in the future. As the standards have evolved, they have often taken cues from JavaScript libraries such as Prototype to determine the next generation of functionality. In fact, a native Array.prototype.forEach() method is defined in ECMAScript 5 that works much like Prototype’s each() method. The problem is that you don’t know how the official functionality will differ from the original, and even subtle differences can cause big problems.

It’s just as easy to remove JavaScript methods as it is to add then. Of course, overriding a method is one form of removing an existing method. The simplest way to eliminate a method is to set its name equal to null:

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

Setting a method to null ensures that it can’t be called, regardless of how it was defined. If the method is defined on the object instance (as opposed to the object prototype), then it can also be removed using the delete operator:

var person = {
    name: "Nicholas"
};

delete person.name;

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

This example removes the name property from the person object. The delete operator works only on instance properties and methods. If delete is used on a prototype property or method, it has no effect. For example:

// No effect
delete document.getElementById;

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

Because document.getElementById() is a prototype method, it cannot be removed using delete. However, as seen in an earlier example, it can still be set to null to prevent access.

It should go without saying that removing an already existing method is a bad practice. Not only are developers relying on that method to be there, but code may already exist using that method. Removing a method that is in use causes a runtime error. If your team shouldn’t be using a particular method, mark it as deprecated, either through documentation or through static code analysis. Removing a method should be the absolute last approach.

In object-based inheritance, frequently called prototypal inheritance, one object inherits from another without invoking a constructor function. The ECMAScript 5 Object.create() method is the easiest way for one object to inherit from another. For instance:

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

var myPerson = Object.create(person);

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

This example creates a new object myPerson that inherits from person. The inheritance occurs as myPerson’s prototype is set to person. After that, myPerson is able to access the same properties and methods on person until new properties or methods with the same name are defined. For instance, defining myPerson.sayName() automatically cuts off access to person.sayName():

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

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

The Object.create() method allows you to specify a second argument, which is an object containing additional properties and methods to add to the new object. For example:

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

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

In this example, myPerson is created with its own value for name, so calling sayName() displays “Greg” instead of “Nicholas.”

Once a new object is created in this manner, you are completely free to modify the new object in whatever manner you see fit. After all, you are the owner of the new object, so you are free to add new methods, override existing methods, and even remove methods (or rather just prevent access to them) on your new object.

Type-based inheritance works in a similar manner to object-based inheritance, in that it relies on the prototype to inherit from an existing object. However, type-based inheritance works with constructor functions instead of objects, which means you need access to the constructor function of the object you want to inherit from. You saw an example of type-based inheritance earlier in this book:

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

MyError.prototype = new Error();

In this example, the MyError type inherits from Error, which is called the super type. It does so by assigning a new instance of Error to MyError.prototype. After that, every instance of MyError inherits its properties and methods from Error as well as now working with instanceof:

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

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

Type-based inheritance is best used with developer-defined constructor functions rather than those found natively in JavaScript. Also, type-based inheritance typically requires two steps: prototypal inheritance and then constructor inheritance. Constructor inheritance is when the super type constructor is called with a this-value of the newly created object. For example:

function Person(name) {
    this.name;
}

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

Author.prototype = new Person();

In this code, the Author type inherits from Person. The property name is actually managed by the Person type, so Person.call(this, name) allows the Person constructor to continue defining that property. The Person constructor runs on this, which is the new Author object. So name ends up being defined on the new Author object.

As with object-based inheritance, type-based inheritance allows you flexibility in how you create new objects. Defining a type allows you to have multiple instances of the same object, all of which inherit from a common super type. Your new type should define exactly the properties and methods you want to use, and those can be completely different from the super type.

The facade pattern is a popular design pattern that creates a new interface for an existing object. A facade is a completely new object that works with an existing object behind the scenes. Facades are also sometimes called wrappers, because they wrap an existing object with a different interface. If inheritance won’t work for your use case, then creating a facade is the next logical step.

Both jQuery and YUI use facades for their DOM interfaces. As mentioned previously, you can’t inherit from DOM objects, so the only option for safely adding new functionality is to create an facade. Here’s an example DOM object wrapper:

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();

The DOMWrapper type expects a DOM element to be passed into its constructor. That element is stored so that it can be referenced later, and methods are defined that work on that element. The addClass() method is an easy way to add CSS classes for elements not yet implementing the HTML5 classList property. The remove() method encapsulates removing an element from the DOM, eliminating the need for the developer to access the element’s parent node.

Facades are well suited to maintainable JavaScript, because you have complete control over the interface. You can allow or disallow access to any of the underlying object’s properties or methods, effectively filtering access to that object. You can also add new methods that are simpler to use than the existing ones (as is the case in this example). If the underlying object changes in any way, you’re able to make changes to the facade that allow your application to continue working.