How I document my code

This week, one of my students asked me about the way I add inline documentation to my code.

You may have seen somethings like this:

/**
 * Update the settings object
 * @param  {String} key The setting key
 * @param  {*}      val The new value
 */
var setting = function (key, val) {

	// if the setting doesn't exist, bail
	if (!(key in settings)) return;

	// Update the settings
	settings[key] = val;

};

They asked:

The comments with @param and @return—I know what they mean, they show what parameters this method expects and what this method should return. But my question is are these comments for the human reading code or for some type of QA/testing software?

Great question!

The short answer is both. I write my inline documentation with the JSDoc style, which is commonly used among JS developers, and so is a bit of a “shared documentation language”:

It can also be parsed by build tools to auto-generate documentation, but you see it used in documentation a lot to explain what the parameters are, the input types they expect, what they return, and so on.

There are other tags you can use, too. They include things like @since (the version in which it was added), @deprecated (for no longer supported methods), @todo (for works in progress). and more.

There’s also a related PHPDoc, which uses the same conventions. For a while someone tried to get a CSSDoc version going that never really caught on, but I use it anyways because I like the consistency.