Expressive Names

If the method name is expressive, we think there is usually no need to comment it. But as with any other method, documenting them gives you time to re-think about what you are testing and it also enables you to pass this information on to other developers (or to yourself a couple of weeks later).

In Growing Object-Oriented Software, Guided by Tests, Steve Freeman and Nat Pryce advice to name tests in terms of the features that the unit under test provides. Since test methods are only called by the test framework through reflection, we can give test method names any length. E.g. (taken from their book) for the features of a list:

• holdsItemsInTheOrderTheyWereAdded
• canHoldMultipleReferencesToTheSameItem
• throwsAnExceptionWhenRemovingAnItemItDoesNotHold

This convention has been invented by Chris Stevenson. You may have a look at the test dox report of Stevenson's TestDox project and its unit test report to get further examples for this approach.

In case you are looking for a Maven 2 plugin that generates reports on your tests, please have a look at our smartics-testdoc-tools project.

Conclusion

Our advice is to not document test methods.