A little while ago, I had a discussion with one of my colleges with regards to documentation. His argument was that the best documentation was the code. My argument was contrary to that.

I thought I would discuss my thoughts here.

Te get things started, lets say you have the below code…

I’ve changed the variable names to make it a little obscure, but given its only half a dozen lines of code, can you tell me in 10 seconds what it does?

My guess is that you can’t. I couldn’t.

I could write a word document that describes the functionality, it could say…

Given 2 numbers, the two numbers are multiplied together and the result is returned.

Ah, now you say, I know what it does!

Are you sure? Word documents can be incorrect or out of date. You cannot rely on them.

So what is next?

This is where my argument comes in. My thoughts are that the best documentation is the tests. Not the code, and not the description of what the document does.

So lets write a test.

As you can see, the tests clearly show what the functionality is.

When we run it, We get confirmation.


So now we know that the method adds two numbers.

Now I hear you say, “Tests are not very user friendly, how is a business person suppose to understand this?”

Well, this is where my second part of this discussion comes in.

There is an open source project called Concordion that can help with this.

Concordion allows you to specify the functionality as examples into an HTML document. It uses the “<span>” tag to mark out sections of the document to be executed.

So, for our little example, our HTML specification would be:

Which renders to:

Test FizzBuzz with Concordion

If the Fizz is 1 and the Buzz is 1 then the FizzBuzz should be 2

If the Fizz is 2 and the Buzz is 2 then the FizzBuzz should be 4

If the Fizz is 3 and the Buzz is 3 then the FizzBuzz should be 6

If the Fizz is 4 and the Buzz is 4 then the FizzBuzz should be 8


All very readable.

The next step is to add a fixture.  A fixture is a bit of code that links the HTML page to the system you are trying to test.

For this simple execution, the fixture is:

Now, when we execute the fixture, we get:


As you can seem the results are green. If for example, we got something wrong, we would get.


So, if we ties this into a continuous integration suite such as Jenkins or Bamboo, we should always have up to date documentation that has been verified and human readable.

Now, if we need to add more tests, we no longer need to write code for this particular scenario. Why? Because we have decoupled “What we are testing” from “How we are testing“.

The fixture controls how we test the method, but the HTML page controls what we are testing. So, to add more tests, provided we haven’t changed any functionality, we just need to modify the HTML page.

Finally, in this example I used Concordion. But there are other tools out there such as Fitnesse which is wiki based, Cucumber and JBehave which is Text file based and numerous others.