Documentation
Introduction
The amount of documentation produced as part of a software project varies dramatically. Before digging in to when and how it's appropriate to document your code, I'll first define how I'm using the term.
Documentation in the context of this chapter means things that are produced to help other developers understand the software product and code, but that aren't the executable code or any of the other resources that go into the product itself. Comments in the code, not being executable, are part of the documentation. Unit tests, while executable, don't go into the product—they would be documentation, except that I cover automated testing in Chapter 5, Coding Practices. UML diagrams, developer wikis, commit messages, descriptions in bug reports, whiteboard meetings: these all fulfil the goal of explaining to other developers – not to the computer – what the code does, how, and why.
On the other hand, documentation...
