Tell me more ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.
up vote 4 down vote favorite
1

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 ?

share|improve this question

3 Answers

up vote 5 down vote accepted

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...

share|improve this answer
up vote 1 down vote

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.

share|improve this answer
up vote 0 down vote

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.

share|improve this answer
1  
I find a good suite of unit tests immensely helpful in documenting code. They provide a reference implementation on how someone's code ought to be used, along with the proof that the code behaves properly when used that way. – Bill Michell Sep 21 '11 at 5:36
@Bill - no argument on that, its helpful. It doesn't replace proper documentation. – littleadv Sep 21 '11 at 5:54
Depends on the audience for your documentation - but in some cases you are definitely correct. – Bill Michell Sep 21 '11 at 6:06
Ideally unit tests shouldn't be the only documentation of a system - but in the real world, 9 projects out of 10 are working with legacy code where it may be considered lucky to have any documentation whatsoever. And in this case, I prefer a good set of running and passing unit tests over a bunch of documents which may be totally out of sync with the actual code. (Yes, even the Javadoc can.) – Péter Török Sep 21 '11 at 7:05
@PéterTörök Yeah... I moved between several different employers, some very well known companies. A lot of legacy code. The only unit tests ever - the ones I wrote. So you were very very lucky. Don't assume that what you saw is what happens everywhere. And even if you have a set of unit tests... Who said that they're correct? Who said that they cover what they should? Who said that the expected results are what they are? Why do you assume that the unit tests are not out of sync? Just because they "pass"? Nonsense. – littleadv Sep 21 '11 at 7:13
show 1 more comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.