3 ms·

If you anticipate that anyone will ever use or maintain your code in the future (including you), you should document it. Right, I think we don't disagree that

If you anticipate that anyone will ever use or maintain your code in the future (including you), you should document it. Right, I think we don't disagree that much. In particular, if you don't anticipate your code being used or maintained for very long, don't document it! Both of us worked on a lot of throw-away code over the years after all ;)

sanderjd 12y ago
This reminds me of this frequent YAGNI-vs-"design" debate that keeps coming up as well. It all comes down to how educated your guesses are about the future of whatever you're building!
- 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 ago
    Well, 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.

sanderjd 12y ago

This reminds me of this frequent YAGNI-vs-"design" debate that keeps coming up as well. It all comes down to how educated your guesses are about the future of whatever you're building!

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 ago
  Well, 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.