Why code documentation matters more than it looks

It comes up on almost every project, usually later than it should. Code documentation is easy to treat as a detail, and that is exactly why it is worth a few minutes of attention.

Most development decisions are really maintenance decisions wearing a different hat. Write the reasoning down alongside the decision, because the reasoning is what changes first.

The reason this keeps coming up

Document why, since the code already shows what. The cost of getting this wrong is rarely visible on the day it happens. It is worth deciding this deliberately rather than inheriting whatever the last person set up.

A README that gets someone running in ten minutes is worth a lot. This is the sort of thing that compounds, quietly, in both directions. If it only works because one person remembers to do something, it does not work yet.

The mistakes we see most

Out-of-date docs are worse than none. None of that requires a large budget, only a decision and someone to own it. It rarely shows up as a line item, which is exactly why it slips.

The short version

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

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