Automatically Generated Documentation

I talked in the last section about an economic trade-off associated with producing documentation: whether the cost of production is lower than the opportunity cost of not having that documentation available later. The balance can be tipped in favor of producing documentation in two ways: either by decreasing the cost of production or by increasing the value of the documentation.

The automatic generation of documentation from code—often called reverse engineering the documentation—is a tactic used to drive down the cost of production. The idea is simple: if developers can always create the docs at a moment's notice from the source code, they can always avail themselves of up-to-the-minute descriptions of how that code works.

Reverse engineering tools, which usually produce UML diagrams, a particular format of documentation discussed later in the chapter (To be clear, I'm not talking about tools that extract documentation embedded...