No code without documentation

I recently, by the good graces of the corporate overlords, acquired a license for the professional edition of dhtmlxGrid, a JavaScript-based solution for advanced grid display in a browser (think jqGrid, but with more features). My task: to write a batch of AJAX functions and the like to load data from a database, then display it and make it editable via the grid.

It didn’t seem like that terribly difficult of a task - just break down database actions into individual components (get columns, set values, etc.) and hook up all the right dhtmlxGrid methods. That’s where it started to go sour.

The issue was not with dhtmlxGrid itself - the table is a fairly solid piece of code, and wound up being flexible enough to accommodate the various tweaks and demands our clients exerted on it. The problem lay in trying to figure out exactly how to get dhtmlxGrid to do precisely what we wanted it to do, and this was a problem for exactly one reason:

Their documentation is terrible.

Go ahead, take a look. It starts out well enough - the “Step by Step, Quick Start Guide” does indeed provide a quick start to using the grid - but once you start trying to look up any reasonably advanced functionality both the English and the code samples lose all coherency.

Take, for example, what should be a relatively trivial task: the word came down from on high that cells in the grid should enter edit mode on a single-click, not a double-click. Where should you look in the documents to learn how to do this? Would it be in Configuration, or perhaps Cells Manipulation, or maybe Events?

Turns out this particular task is buried near the bottom of Cells Manipulation under the heading “Enabling Edit Events” (why isn’t it in Events, again? Or at least cross-linked?). Whatever. We found it.

The next issue: what’s with these click, dblclick, and f2Key arguments? What are they? The first two are listed as “(true

false)”, and the last as “enable

disable”, but both click and dblClick are DOM events as well, so what should I pass? In essence: are the provided arguments example values, or variable names? Scanning back over the remainder of the documentation provides no clear distinction: some methods are documented formally, with function prototypes, but others are “defined” entirely by examples of their use.

Nevertheless, we plowed forth with dhtmlxGrid, eventually finding (or hacking in) ways of accomplishing everything we wanted done. But we came out on the other side with a very fundamental understanding every good programmer should have:

Your project can be the best on the face of the Earth, but without good documentation, the best code means nothing.

Harsh words? Yes. Justified? Absolutely. dhtmlxGrid is a solid product, and the professional edition supports some very advanced features like column freezing and nested grids. But those features are absolutely useless to paying customers unless the developers tasked with using them can figure out how.

This is a lot of the reason why I’ve been pushing the use of Doxygen and Trac so hard at my company this summer, and been using them thoroughly myself: as a contractor, I know without a doubt that I’m leaving the company when my work is done (or when school starts again, whichever comes first). As such, it’s critical that whatever developer comes after me is able to pick up my work with relative ease. If I can save my successor even a day of trial and error when updating and working with my code by documenting it ahead of time, that’s a major victory. And it’s been paying off; the two new developers we’ve hired and our local HR person have all commented on the completeness of my docs, and the devs have saved a couple days on getting up to speed already.

Exactly how to write good documentation is somewhat beyond the scope of this particular post, but there are positively millions of books, sites, other blog entries, and even speakers that will tell you - at great length - what precisely “good documentation” entails. But at this point, with the advent of tools like Doxygen, there’s no reason whatsoever for developers not to provide at least minimal documents with the code, and to write those documents during development, so the functionality is fresh in their minds when writing. (That last bit is critical - it’s orders of magnitude easier to document a function you just wrote or are about to write than it is to document a function you wrote last week.)

By the way, it turns out the arguments to that grid setup function were all booleans, which I only figured out after trying DOM events and strings for all three. I bet the developer knew that when he was writing the function.