Our team is working on a new project with Node.js on the backend. Within our team, we have some JavaScript folks and some Rubyists.

While working with one of our libraries, we noticed a hole in the documentation. That hole centered around a JavaScript convention. The Javascript folks took this convention for granted and didn’t even notice the hole in the documentation. The Rubyists, less familiar with JavaScript conventions, were all like “wtf is going on”, “how the $%^ do I use this library”.

This wasn’t cool. Documentation should not take conventions for granted. 

The Crux: Error-First Callbacks

Our JavaScript developers and the library took for granted two JavaScript conventions:

  1. If the last parameter of a method is a function, that parameter is used to track async execution of code. Calling that function means “async execution has completed.”
  2. When you have a callback function like this, it takes two parameters.
    • The first parameter is any errors that occurred.
    • The second parameter is any success object.

Many native modules and libraries all use this pattern. It even has a name: error-first callbacks! It’s a fundamental part of the JavaScript language. Many, many libraries embrace this convention:

What makes this frustrating for non-JavaScript developers is that some of these libraries document this pattern; other libraries (that will remain unnamed) don’t, and that sucks.

Pay attention to conventions. Document them.

When our developers were authoring new code, the JavaScript folks saw some conventions and took them for granted. The Ruby folks didn’t know the conventions and were lost.

JavaScript can and should be better. Undocumented conventions make it harder for new developers to enter the community, contribute, and grow. Document your conventions so that the developers of tomorrow can learn as you did!

Related Articles/Resources




Tagged with: