2 ms·
Yeah, but in this case the losses are bounded, and the upside is huge. You spend 10% (or whatever) of your coding time maintaining documentation, and your long
by timr 12y ago
Yeah, but in this case the losses are bounded, and the upside is huge. You spend 10% (or whatever) of your coding time maintaining documentation, and your long-term expected value is much higher than that. Even if you're not able to predict what code gets re-used and what code doesn't, it's one of the highest-payoff bets you can make in software.
About the only times I accept Bill's premise is when you know that you're doing something throwaway (i.e. never gets checked in), or when you're so pressed for time that the cost of doing the documentation is the difference between success and failure (but if you're that bad off, you're doomed anyway). Most of the time, documentation doesn't get written because it isn't immediately "fun" for the coder, and nobody is enforcing it. There's no rational reason otherwise.
- sanderjd 12y agoWell, I might agree with you, or I might not, depending on how we're defining "documentation". If we're talking about the sort of documentation the OP is talking about, which is crucial for any interface that you're releasing to the public, then I don't agree. Documentation like that impedes change and its value doesn't always come out on the right side of the trade-off. Now, if we're talking about more informal documentation used to clarify thought process in confusing areas or writing good commit messages to document the thought process behind a set of changes, then yeah, I agree that everybody should always do that.