Three myths about code documentation

The advice here is unglamorous, which is probably why it gets skipped. A few things about code documentation that get repeated more often than they get checked.

The question is rarely whether something can be built, but what it costs to keep running afterwards. If it only works because one person remembers to do something, it does not work yet.

“It only matters for big sites”

Document why, since the code already shows what. There is a version of this that is over-engineered, and it is worth avoiding. The failure mode is not doing it wrong, it is doing it once and assuming it stays done.

“We can deal with it after launch”

Sometimes true, usually expensive. The reasoning matters more than the rule, because the rule has exceptions.

“Our platform handles it”

Out-of-date docs are worse than none. It is worth being explicit about, because assumptions differ quietly. Budget a little time for it every quarter and it never becomes a project of its own.

In practice

Code gets read far more often than it gets written, and usually by someone with less context than the author had. Three things worth confirming about code documentation before you move on:

• Someone can say what the current setup is without going to look
• Out-of-date docs are worse than none — and you know whether that is true here
• There is a way to tell whether the last change to this helped

If you want a second opinion on how yours is set up, ask.