Code documentation: the questions we get asked most

It comes up on almost every project, usually later than it should. The questions about code documentation that come up most often on our calls.

Code gets read far more often than it gets written, and usually by someone with less context than the author had. Assume whoever inherits this will have half your context and none of your patience.

Do we need to care about this?

Document why, since the code already shows what. The cost of getting this wrong is rarely visible on the day it happens. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.

Can it wait until after launch?

Occasionally. More often the post-launch version costs several times the pre-launch one. That sounds obvious written down. It is still the thing most often skipped.

How do we know it is working?

Out-of-date docs are worse than none. The teams that handle this well are rarely the ones with the biggest budgets. Budget a little time for it every quarter and it never becomes a project of its own.

What this looks like day to day

Most development decisions are really maintenance decisions wearing a different hat. Three things worth confirming about code documentation before you move on:

• Someone can say what the current setup is without going to look
• Document why, since the code already shows what — and you know whether that is true here
• There is a way to tell whether the last change to this helped

Worth checking on your own setup before it becomes someone else's problem to fix.