Implementing unit-tests has become (quite) standard for many developers. We like to propose an additional purpuse for such tests: interface specification or documentation.

Take tests as detailed (and highly agile!) documentation, and only alternatively as real tests (for verifying application behavior).

A unit-test contains the following information:

• prerequisites that have to be (programatically) created to use the specific interface
• showing in what constellation or context the interface can be used
• what kind of consequences can be expected after the implementation of the interface has been used (by the assert statement)

Instead of any graphical or textual specification or description you can write unit-tests and use one or several test methods as documentation (or specification).

In case you integrate these tests from your code repository in your documentation, you’ll get up-to-dateness of the documentation for free.

Example for unit-test as interface documentation

package joptsimple.examples;
import joptsimple.OptionParser;
import joptsimple.OptionSet;
import org.junit.Test;
import static org.junit.Assert.*;
public class ShortOptionsTest {
    @Test
    public void supportsShortOptions() {
      OptionParser parser = new OptionParser( "aB?*." );
      OptionSet options = parser.parse( "-a", "-B", "-?" );
      assertTrue( options.has( "a" ) );
      assertTrue( options.has( "B" ) );
      assertTrue( options.has( "?" ) );
      assertFalse( options.has( "." ) );
   }
}

Apply behaviour driven development (BDD)

You could develop your system or parts of it in behavious driven manner (BDD). Then the specification of the system works both as documentation and as automated test. One possible framework supporting BDD this is Cucumber, another is Spockframework.