Choosing a jQuery plugin is surely more difficult than using it. There are thousands of jQuery plugins on the web that perform a wide range of tasks but only a few of them are really useful and usable. The overwhelming majority of jQuery plugins make you feel frustrated because we usually spend a significant amount of time trying to make them work but without results. Sometimes we feel stupid, other times we simply trash the plugin and start another Google search. That's because such plugins were not designed with usability in mind. Usually we define a plugin poor when it doesn't satisfy all the jQuery coding guidelines. This can be misleading, because even a poorly written plugin can turn out to be the right plugin to us. It's not about coding: it's all about usability.
First of all, a jQuery plugin should be well-documented. Being well-documented doesn't simply mean listing all the default options with their values. Instead, it means that every option (or option combination) should be documented and have a demo page. Demo pages must be atomic and not too complex. One should grasp how an option works by simply viewing the corresponding demo page. For example, Cycle is well-documented whereas scrollTo is not. In fact, scrollTo puts every possible option into a single demo page, thus making life harder for plugin users. I spent 3 (3!) hours trying to figure out how scrollTo works!
Documentation has nothing to do with JavaScript or JSDoc comments: plugin authors should provide a detailed documentation as separate HTML pages. Unfortunately, the jQuery community mostly focuses on code quality without taking this aspect into proper consideration. Instead, this aspect is crucial because a plugin user could not spend hours to make a plugin work.
Further, code snippets should be provided as an aid to users. Generally, plugin authors assume that you will view the source of the page to see how the plugin works. This is another useless waste of time: we need that code because our client asked us to add another cool effect to the site and we simply do not have the time to scroll the source code! Authors should include code snippets on every demo or documentation page for the sake of a copy and paste made in a hurry.
Plugins, however, should be flexible. Plugins that are bound only to a particular HTML element are surely useful, but only for one specific task and only on a specific element. For example, a slideshow plugin should work either on a div
or a ul
. That's because sometimes we work on the markup chosen by other developers (e.g. PHP developers who have implemented a template system) and we have to adapt our code to that markup.
Flexible plugins are also plugins that not only fulfill a specific task now in the present but are also capable of being used in the future for other tasks. For example, a Twitter plugin may be used now only to fetch the latest tweets, but in a not too distant future it should allow us to format Twitter dates or to compute the time elapsed between each tweet.
In a nutshell: flexibility and usability are the signs of a plugin that is right to us.