The real cost of ignoring code documentation

It comes up on almost every project, usually later than it should. Nobody bills you for neglecting code documentation. The cost shows up somewhere else.

The question is rarely whether something can be built, but what it costs to keep running afterwards. Write the reasoning down alongside the decision, because the reasoning is what changes first.

Where the cost lands

• Time spent on work that should not have been necessary
• Enquiries that quietly never arrive
• Document why, since the code already shows what
• Rework, once the problem is finally visible

A README that gets someone running in ten minutes is worth a lot. Small and consistent beats large and occasional here. Assume whoever inherits this will have half your context and none of your patience.

A reasonable first step

Out-of-date docs are worse than none. It is worth being explicit about, because assumptions differ quietly. It is the sort of thing that looks like polish right up until it costs you an enquiry.

How to tell if yours is fine

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 any of that sounds like a description of your current setup, it is fixable.