Agile documentation
The other day we were chatting about the method names in our test classes. We had noticed that one of our method names was about 40 characters long and reads like a sentence. This sounds stupid, but actually it makes things really easy to read in the test logs.
I got to thinking that you could do a lot worse for auto-generated test documentation than just de-camelizing the test method names and treating them as bullet point documentation for the classes. Sort of like javadoc-lite. So “public void testFooIsNotNull()” becomes “foo is not null”. An hour’s worth of coding using Joe’s qDox and I had a working prototype.
To give you an idea of how readable this kind of documentation can be, here is the output when it is run on its own code:
NamePrettifier
- Title has sensible defaults
- Cater for user defined suffix
- Cater for user defined prefix
- Test name is converted to a sentence
- Is a test is false for non test methods
DocumentGenerator
- Start class and end class are called
Main
- Main parses this test
- Main handles multiple document generators
- Ignore non test classes
- Ignore set up method
Neat huh? I think it almost reads like a mini spec of the system. Simple and to the point.
I’ll post the code as soon as I get a chance to clean it up a bit… not that there’s much of it :-)
Oh, and like all good geeky code there is a self-referential test in main: “Main parses this test”. And yes, I did do that test-first.