Tests and Documentation

Tests are a very useful tool because they are executable and show when things are working and when they are not. Because of these advantages, we can use them as a part of our documentation.

At a first glance, the names of the unit tests provide a very useful list of behaviors that work (or not) in our system. We could combine these names with Javadoc style documentation on the test methods and with smart tools in order to generate the documentation of our system. Tests can at least be used as usage examples for a specific part of our code, if not more than that.

It would be great to have an IDE plugin that generates usage examples from tests as part of a class documentation.

Another audience for documentation is the business analysts, product managers, or product owners who want to see the requirements and their stages of implementation. A general technique called “executable specifications” allows the creation of specifications that execute against the production code to show whether a case is implemented or not. The most common implementation of this technique is with Behavior Driven Development (BDD) tools and frameworks, such as Cucumber and HipTest, but older implementations exist such as Fitnesse.