DDD: Documentation Driven Development?

Documentation seems to be quickly defining itself as one of my specialties at work. Not that I mind; I've always felt that documentation was nearly as important as the source code itself. But I spent a large time again this week going through code and writing down what it did, without making any substantial changes to how it ran. And I think it is actually a really fun pastime^[1].

JSDoc

/**
 * Solves equations of the form a * x = b
 * @example
 * // returns 2
 * globalNS.method1(5, 10);
 * @example
 * // returns 3
 * globalNS.method(5, 15);
 * @returns {Number} Returns the value of x for the equation.
 */
globalNS.method1 = function (a, b) {
    return b / a;
};

I also have sort of been pidgeonholed as a Javascript developer… Because the only alternative is python^[2]. So, I was glad to discover that the Javascript ecosystem had something not dissimilar to JavaDoc, which I have used in the past. Since we minify all of our code anyway, there's no need to worry about adding some comments here or there, especially not when we'll have a full documentation site afterwards.

The tool I'm talking about here is called JSDoc, which is as similar a name as it a tool. The basic concept is to document Your code with comments in a specific format, so another program can slurp^[3] the code and extract the comments to turn into a static website full of documentation. There are specific symbols to use to denote things like returns or parameters, and in general it is Good Enough™ for this purpose.

This also makes the resulting Javascript respond (almost) like a Lisp REPL with regards to functions being self-documenting! At least, when a language server is running underneath. I'm reminded of that meme about emulating a fraction of our power. Oh well, at least I get to code, yeah?

[1]: Writing Documentation is a completely different skill to me than writing code. It's one thing to be able to define a working system, and it's another thing completely to write something that tells a stranger how that system works.

[2]: I don't really have the time or space here to write out all of the reasons I dislike Python right now, but some highlights include the significant whitespace, the (very) low bar for entry and quality, the 2/3 split still existing after nearly a decade, and the failure to adhere to "There's only one way to do it!" I have to use it in some of my classes at school, and yup, I still hate coding in Python.

[3]: This is one of my favorite bits of jargon. Here is a definition, if You are unfamiliar.