Writing java doc comments for unit test cases

Question

In my opinion, the unit test cases itself serve as a documentation for the code. My company wants me to write detailed java doc comments on top of unit test cases. Is it necessary to do so? Do you write comments like that ?

Answer 1

What I do is JAVADOC-comment :

• the class, indicating which class is unit tested (even though it should me obvious since the best practice on that subject suggests that the name of the test case should be the name of the class + "Test" or + "TestCase"). This is done using the {@link XXXClass} JAVADOC comment

• the methods, indicating which method is tested ({@link XXXClass#method1}). Sometimes I need to have multiple test methods for one method of a class to properly test all paths. When it happens, I write one additional line stating what path I am testing inside (but I never stray away from my one-line convention)

Apart from that, no other comment. To take their attention elsewhere maybe you could use something like Cobertura to generate pretty code coverage graphics and make them happy that way :-)

Additional note: I am referring to unit test cases, if we're talking about integration test cases, then one or two more lines to explain what is going on may indeed be necessary...

Answer 2

Documentation requirements for any code are fairly completely covered in the answers to this question: My boss wants a narrated line-by-line English explanation of our code

As a summary of the answers you'll see there, "It depends on your situation". There are cases where it is reasonable (and encouraged), and others where it is a waste of your time.

Answer 3

Javadoc comments can be extracted and formatted in a separate reference document, unit tests cannot. Also, bear in mind that what you write in words can be different from the actual code, and usually you are describing in words the actual expected behavior. One of the ways to find bugs is to compare documentation to the actual code, if they don't match - it's a bug (in either of them, and sometimes - both).

Unit test is for testing, not for documentation. Using unit test as documentation is wrong and shouldn't be done.