Thoughtworks’ Joe Walnes has posted a link (joe.truemesh.com/blog/archives/agile/000047.html)
to an interesting project called TestDox (agiledox.sourceforge.net/).
Given a suite of JUnit (www.junit.org)
tests, it generates documentation.

Like FIT (fit.c2.com), this is an
interesting bridge between executable code and documentation. TestDox
converts camelCasedTestMethodNames into separate words, so this code

  public class DogTest extends TestCase
  {
    public void testBarksAtCats() {}
    public void testEatsALot() {}
    public void testSleepsWhenNotBarkingOrEating() {}
  }

…would produce the documentation that looks basically like
(untested):

Dog

  • Barks at cats
  • Eats a lot
  • Sleeps when not barking or eating

This has arguably limited usefulness, and it depends trickily on class and
method naming conventions. But, it starts the ideas flowing, and
TestDox’s parent project (Agiledox) will hopefully expand and
explore these much further. It may sound like heresy to the XP world, but
I’d be interested in being able to do this sort of thing round-trip
(documentation -> test -> documentation -> test ->
documentation -> …)

In my own unit testing, I haven’t always been so methodical about
using method names that describe a characteristic of the entity being
tested. It’s not that I don’t use descriptive names, but I may
include tests with names like "testEatBadTastingFood()", which
describes a specific scenario but not an ongoing behaviour of dogs. Running
my tests through TestDox might generate misleading documentation.
It’s not that dogs generally eat food they don’t like. I just
wanted to test what a dog would/should do in the eventuality that they
did eat bad food. I’m not sure if my current behaviour is bad
or good, but it will definitely be something I think about next time I sit
down to do some coding.

A fear I have is that, with this tool in place, I may be tempted to think
about what the generated documentation will look like as I write my tests.
This would create a new and potentially conflicting objective in my test
writing. And, since I tend to do test driven design, it would ultimately
impact my design and coding decisions.

I’m not ruling out the possibility that this change in thinking would
improve my code. I guess I’ll just have to try and find out.