Years ago I had an officemate who said that if it took more than one simple sentence to state the function of a [Fortran] subroutine, it was doing too much. I think that is a good summary of how the feedback between writing internal documentation and coding an implementation can often help you to avoid documentation errors and, at the same time, to write better code. For example, the top-level documentation of a class might simply be, "Objects of this class handle input of a user configuration file." Note the absence of the word "and." If this statement is originally correct, it should likely stay correct.
Of course, a high-level class like this one would typically hand off much of its actual lower-level work to other classes. In fact, the suggested documentation helps you realize this. After all, it doesn't say "input AND storage" of the user file. So that reminds you of the desirability of another class that is just a data structure for representing a user configuration. And by then, you start to appreciate modularity. If for example, you want to develop some piece of code that relies on a user configuration but you don't want or need to get one from input, you can just create one directly.
As another example, it might not be until later that you realize there is a need for handling multiple user configuration files. Your previous documentation referencing "a configuration file" should make you thinking seriously about the probably preferable solution of developing a new class that "manages the use of multiple configuration files" rather than adding to the functionality of the original class such that its top-level documentation is no longer correct.
Of course you aren't always going to come up with the best functional decomposition on your first try. That's where refactoring comes in. But it has been my experience that my own code is easier to reuse, easier to maintain, and easier to extend the more closely I follow my old officemate's advice.
SusanJ
