I have long felt that one good reason for unit tests should be that of "Executable Documentation." Unit tests should illustrate the intent of the developers, as they wrote the code, so that we can make sure the code does what was intended. In contrast to other types of documentation, these tests are actually compilable and runable. There is very little chance that they can be out of sync with the actual product code, as long as there is a Continuous Integration [CI] system in place to execute the tests. This is in contract to documents, and other written forms. The only document that is kept in sync with source is one that is automatically extracted from the code.

All project documentation has a cost associated with it - both for creating it, as well as maintaining it. It's these ongoing costs that we on Agile project would like to keep to a minimum. We need only as much documentation as required by stakeholders, and no more. Unit code "documentation" is usually required by the "development management" stakeholder, usually implicitly. Anything else should probably be specified directly by the product owner, and should be a specific task on the sprint backlog to produce.

Documentation that is in sync with the product code, such as unit tests and automatically extracted documentation, or even release notes, has the lowest total cost of ownership [TCO] for the project long-term. See what you can do on your current or next project to lower your TCO for documentation with automation and Executable Documentation.