Rules For JavaScript Library Authors

Rules For JavaScript Library Authors

I wrote this about six months ago before starting work on base2. I decided not to post it at the time as I thought it sounded a little pompous. On reflection, they aren’t bad rules and I managed to stick to them. So, here the rules I wrote for myself back in October.

1. Be unobtrusive 

My HTML doesn’t want to know about your JavaScript. 

2. Object.prototype is verboten! 

This is so important that it needs a rule all to itself. Objects are the basic building blocks of JavaScript functionality. Don’t mess with them. 

3. Do Not Over-extend 

The less you extend JavaScript’s built-in objects the better. Don’t get me wrong. Native JavaScript objects are a little sparse on useful methods. You will feel obliged to add one or two of your own. But “one or two” is not enough for the creative (library) programmer. Stop! Just add what you need. The less you extend JavaScript’s built-in objects the less you will clash with other libraries. 

4. Follow Standards 

As a library writer you are defining patterns of JavaScript code. Patterns are signs of weakness in programming languages. Remember, JavaScript and the DOM are continually being specified. If you are going to “fix” something then look to see if it has not already been fixed. Consider available solutions. If you follow standards, then follow them closely (e.g. don’t skip a parameter on a forEach method). 

5. Or Follow The Leader 

Mozilla leads the way in JavaScript. The creator of the language, Brendan Eich, continues to develop it. New language features are available in Mozilla browsers before any other. If you are going to add language features to JavaScript then look to Mozilla standards first. For example, if you want to extend Array to allow an enumeration method, then call that method forEach instead of each. If you do provide missing language features then follow existing standards closely (see above). 

6. Be Flexible 

What if I want to modify behaviour without changing the source code of your library? How easy is that? Not easy enough. Make it easier. 

7. Manage Memory 

People care about memory leaks. Do your job. 

8. Eliminate Browser Sniffing 

It seems that browser vendors will forever compete by adding new features. As a library author you must keep up with the latest fashions. It is not good enough to browse Ajaxian occasionally. You must slavishly read every blog to find the next hack. Browser sniffing can be addictive. 

9. Small is Better 

JavaScript libraries have come of age. Some of them now power premier sites. But we are not all on 2MBit DSL lines. So keep your library small. Better yet, provide a build page that allows me to efficiently build my library according to my needs. 

10. The Tenth Rule 

Good ol’ tenth rule. You can always rely on the tenth rule. The tenth rule is: be predictable. I should be able to guess what your methods do. And if I don’t know what a method is called then I should be able to guess that too. 

11. Bonus Rules 

1. Documentation. Annoying but true. 

2. The more namespacing you use, the less likely I am to remember your phone number. 

3. Remember that potentially millions of people will be executing your code.