The Economics of Writing (Good) Code Documentation

TL;DR: Writing documentation can be beneficial even for a lone programmer writing code that will never be read by anyone else; however, the benefits, when other programmers are involved, are cumulative and potentially huge in terms of time saved (of those programmers) when trying to grok the existing codebase. 

It is well known that programmers in general hate to write documentation. There are lots of reasons for this. For example, in the heat of writing code, the programmer simply cannot envisage what it would be like for someone else to come along in a couple of years and try to understand the code from scratch... And anyway, what does the programmer owe to that future person? (The programmer will likely have moved on by that point...) etc. etc. So, poor documentation (or lack of documentation altogether) is a problem that stems from the programmer, and probably left unfixed by the managers of the programmer, right up the chain of responsibility.

This post isn't an attempt to address these problems. This post is simply to lay out the potential economic costs of not writing documentation (or, vice versa, the benefits of writing documentation). Hopefully, in light of these costs, programmers who currently don't write sufficient documentation might reconsider. Of course, given that the documentation is primarily for others, and not the programmer themselves, this still requires some sense of obligation to others.

So, let's consider a simple scenario: A programmer takes 1 hour to write some code. To write the accompanying documentation would also take 1 hour (say). What are the consequences of writing (or not writing) the documentation?

Let's imagine another member of the team comes along and tries to understand the code.

Without documentation, it might take, say, 2 hours to understand the code. With the documentation it might take, say, 30 mins to understand the code. (These are just arbitrary figures - an experienced programmer will take less time than an inexperienced programmer etc etc.)

So, that 1 hour of writing documentation saves 1.5 hours of time (in the future... and the time is not the time of the original programmer but of a new programmer... but still, from a global point of view this is a win).

Now imagine another programmer comes along and tries to understand the code. Again, the benefits are the same: 1.5 hours of time saved. But the key point is not the numerical figure. The key point is that the benefits accrue EVERY TIME A NEW PROGRAMMER TRIES TO UNDERSTAND THE CODE.

Even in the case of 1 new programmer, writing documentation likely saves time overall. Even if no new programmers look at the code, writing documentation has benefits in terms of forcing the original author to clearly state what a piece of code does etc. Indeed, it is also well known that programmers come back to code they have written previously and find they can't understand it, so documentation can help even if there is only a single programmer writing code.

But the big win, clearly, is when there are multiple programmers who try to understand some existing code. So, please help others (and maybe even yourself!) and write good documentation for your code!

UPDATE 2022-03-28: I guess I should also clarify that I am mostly interested in documentation of the interfaces to pieces of code (or components). The interface is what mostly matters. Although I also  believe in documenting the implementation as well, the benefits to this are a lot less clear and likely much more context dependent. In short: "documentation" refers to "what does someone need to know to use this piece of code" - and this documentation usually accompanies the interface to a component, not the details of the implementation itself.