Best Practices in JavaScript Library Design

John Resig, lead developer of jQuery, went down to the Googleplex and presented on JavaScript best practices, which he learned from developing the popular jQuery JavaScript library. The video of the presentation and the slides from the talk are available from John’s post on the experience.

For my own benefit I’ll recap some of John’s key points made in the presentation. In writing a general purpose JavaScript library you need to deal with browser specific bugs, have enough documentation in place, provide test cases, keep maintenance in mind, and have a solid API design.

In talking about API design, John said to fear adding methods. The more methods your library supports, the more code there is to maintain, support, test, and document. Instead of adding methods to your API you should embrace removing them where it makes sense. If you add/remove methods between releases be sure to provide an upgrade path, preferably through a plugin. For example, when moving from version 1.0 to 1.1 of a library you can provide a 1.1 plugin that eases the migration for 1.0 users.

John reminded the audience that a consistent API is paramount to designing a general purpose JavaScript library. A consistent API means following a naming convention for method names. The naming convention includes method signatures, for example follow a consistent position or order for parameter types. In addition to following a naming convention, you should be clear about behavior.

When developing a enterprise-grade JavaScript library you need to have a good grasp of JavaScript language tricks and features such as closures, encapsulation, local variables, and namespaces. John also recommended not to extend browser native objects because it is hard to get DOM extensions working across browsers. Also a new version of a given browser might introduce functionality or new methods that conflict with those your library adds to native objects.

A key point made by John, which I alluded to before, is to allow for extensibility by introducing a plugin architecture. If you allow end users to create their own extensions you will have less functionality to maintain yourself, you can always defer feature requests to the community. Since much of the functionality can be added as plugins, the core library will have a smaller footprint.

If you are counting on the support of a community of users, John stated the importance of having clear and concise documentation. Documentation is key in fostering a sense of a lively community. Provide documentation in a clear format (something like XML) and allow users to build their own API viewer. Encourage users to build and disseminate cheat sheets, API widgets and viewers, and translations of the documentation. Right from the start, provide enough documentation for the community to get started, such as tutorials on plugins.

Technorati Tags: , , , , , , , ,

One Response to “Best Practices in JavaScript Library Design”

Leave a Reply