12 August 2014

When you're documenting an object/method/variable, ask: What would a stranger -- who knows basic coding & a bit about our project -- need to:

Get or make an instance of this object?

Use a class or function?

Edit this code?

Good documentation is invaluable. It enables new people to join the team, and it takes some of the pain out of code maintenance. It's a balancing act: It should be short yet clear. And of course, you don't want to spend too long on it.

The clearer you can make the code itself, the less documentation is needed (see the notes below on avoiding pointless documentation).
But: readable method and variable names alone are not enough to make code self-documenting.

Things to document:

Assumptions a method makes about the state of things.

Exceptions that may be thrown, and why.

Parameters whose meanings aren't obvious from the names. But there is no need to document the obvious.

There's no point in doc which just restates the function/variable name. You are not writing for idiots.

Type {Object} tells us very little! What kind of object is it?
A common case is where Object is a lookup map, in which case
say what the keys are. Consider using a name which clearly describes the lookup, e.g. tagsetFromTag is clear, whereas tagsets isn't.

Parameters: Can they be null? What happens if they are?

The input parameter url in this example is ambiguous: is this an absolute url, a relative url, or does it not matter because both will give the same output, or does it matter but which to use is specified elsewhere?

Return value: can it be null?

Lifecycle: when can this be called? E.g. does it only make sense after the page has done some initialisation steps.

About

The platypus caused consternation, shattered existing categories. It's existence was undeniable, but how should taxonomic theory be adapted to accommodate this uncomfortable fact? This blog is also hard to classify. It loosely follows the professional interests and activities of Daniel Winterstein. Topics are likely to range from business affairs to new media via data science and abstract mathematics.