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 ?

  • presuming the test code is well written and readable, the primary value of a comment of this sort in test code is as a statement of intent.. That can be very valuable to code reviewers, even yourself in a years time, as it allows you to judge of the code that was written is doing what it's supposed to do, or testing what it's supposed to test. Secondarily you can use systems like JAVADOC or even a simple script to scrape the test names and comments from the code to create a quick bit of documentation on what tests you have and what they are doing. Oct 18 '18 at 21:58

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


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.

  • 2
    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. 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. Sep 21 '11 at 6:06
  • 1
    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.) 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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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