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 ?
- Anybody can ask a question
- Anybody can answer
- The best answers are voted up and rise to the top
What I do is JAVADOC-comment :
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...
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.
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.