This situation is very common at startups, for example.
This situation is very common at startups, for example.
If you anticipate that anyone will ever use or maintain your code in the future (including you), you should document it. The communication overhead of an organization grows as the square of its size, so the returns on the fixed amount of work involved are exponential.
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 ;)
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.
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.
In particular, when I change something I need to know the interface with detail, the input and the output and EXACTLY what the black box is expected to do, special cases included.
I just cant tell you how much time I have wasted in my life because the original programmer FORGOT the interface, or its details.(Hey, I made this 6 month ago, Do you expect me to remember the details?)
I couldn't care less about the blackbox if we are going to change it, but its behavior needs to be documented.
I've found the hardest thing is really deciding what to build. And figuring that out can be helped by writing a lot of docs early. [edit: or prototyping, of course, but they aren't mutually exclusive and depending on how you divide roles that might not be an option]