TDD Versus DDT

Test-driven development (TDD) is commonly accepted as a practical approach for producing high quality production code and high quality unit tests at virtually the same time.

This short article is about an alternative approach, called Documentation-driven testing (DDT). While it does not apply in all situation (which approach does?) I have used it effectively, although until now I’ve never taken the effort to describe how we did it.

This is how TDD works:

1. Write a minimal test for the currently non-existent production code; no more than is needed to make the test fail; and not compiling is a form of failing.
2. Make sure the test fails.
3. Write the production code; program only what is needed to make the test succeed. And yes, take this literally, even if it appears stupid (e.g. returning a constant from a computation method).
4. Make sure the test succeeds.
5. Either go to step 1 or refactor the code and go to step 3.

Now, here is how DDT works:

1. Write Javadoc API documentation for the production code, with a just an no-op implementation. The code should compile and the Javadoc API documentation should be generated.
2. Write unit tests using only that documentation. This should be done by somebody other than the one that wrote the documentation.
3. Make sure the test fails.
4. Implement the production code.
5. Make sure the test succeeds and, if not, find the source of the error (documentation, production code or test code).
6. Go back to step 1 or refactor the code and go to step 5.

Now, what is the advantage of this approach? The main driver is the quality of the documentation, including the consistency with the production code. Note that you should already get a good review of the quality of that documentation in step 2, since a lack of understanding on the side of the unit test author should ring some bells.

It is clear this approach is not applicable everywhere, all the time. As is suggested in Uncle Bob‘s great book Clean Code, avoid comments except for public APIs. There it may be an approach that works for your team; if it works for you (or not) do let me know!