Christian Heilmann

Dear JavaScript Library Developers…

Monday, December 11th, 2006 at 8:48 pm

After spending about three weeks finishing a chapter of the upcoming book introducing JavaScript libraries to non-developers I was quite amazed how tough it is at times to use different libraries.

It was frustrating putting together a set of example scripts for several effects for the oddest reasons, which is why I am now publishing my wishlist for any JavaScript library developers or maintainers. Before you start a new library or expect people to be able to use yours immediately you might want to give these points some thought. For library users this list might be a good “heads up� to see how much work has to go into using a library or how to pick the right library for the job at hand.

Here’s what drove me nuts:

  • Lack of offline documentation. I am writing a lot of code on public transport or in hotel rooms where they consider it still an option to charge me for every 10 minutes online. It is not hard to create a PDF or offer a ZIP of the library documentation even if it is Wiki based.
  • Lack of step by step instructions and examples for effects and elements of the library. Most of the time you either get no examples at all or a single example that shows all the options you have in one script (or a very complex form to play with all of them – which is only marginally better).
  • Lack of unobtrusive examples of code which are those that fall back to working and functioning HTML or HTML+server side script solutions. In the market you will have to develop applications in accordance with accessibility and SEO requirements and both of these require that the page does not rely on JavaScript. It is very easy to create fancy examples that work with JavaScript, but harder to enhance what is already there.
  • There is no problem with trying to improve JavaScript or DOM methods in addition to just fixing bugs and browser inconsistencies. However there is a problem if your extensions break conventions like the event model. I have encountered a library that had addEvent() and removeEvent() methods, but no way to stop the default behaviour of the element. This is an oversight that shows me that this library was never meant to be used unobtrusively or to enhance a server side driven application.
  • Lack of information about browser support and – even more importantly – fixes and updates for new browsers that might come along. This allows your users to update their library includes or subscribe to feeds that tell them about updates and fixes. As a lot of libraries advertise themselves as a helper to make sure you don’t need to know JavaScript this is the least you should do to gain the trust of users. It is easy to claim everything works, but when there are browser specific bugs you cannot expect library users to fix them inside your library.
  • Inconsistency in naming of methods and properties. There is a lot of good documentation on the W3C sites about what an event is, and if you call it action I personally get very confused. If you don’t know JavaScript or the W3C specs that is less of an issue but personally I consider libraries are step towards improving JavaScript and the DOM and not a replacement of them.
  • Trying to replace CSS with library methods. There is a reason why CSS is used for look and feel: CSS parsers are very fast and it is great for maintenance to centralise all look and feel in a spot using one technology. CSS is that technology as it was invented for it. Instead of battling CSS, scripting should piggyback on the CSS parser whenever possible (by adding CSS class names to parent elements) instead of changing a lot of style properties directly. CSS has a lot less options to access content and elements than the DOM has and we can use JavaScript to give CSS developers a helping hand to reach these. There is a reason why there are so many “CSS onlyâ€? solutions out there – people got sick of scanning JavaScripts to find the place to change a look and feel parameter.
  • Don’t play the “mine is smaller than yoursâ€? card. It gives the wrong impression to new developers as they might be tempted to think that your short wrapper methods are all that has to get executed. We all know that they have to be converted to native JavaScript and DOM methods before execution.

Share on Mastodon (needs instance)

Share on Twitter

My other work: