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 ?
Asked
Active
Viewed 2.3k times
11
-
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. – Chuck van der Linden Oct 18 '18 at 21:58
3 Answers
9
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...
Jalayn
- 9,789
- 4
- 39
- 58
1
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.
blueberryfields
- 13,200
- 8
- 51
- 87
0
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.
littleadv
- 4,704
- 27
- 26
-
2I 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 05:36
-
@Bill - no argument on that, its helpful. It doesn't **replace** proper documentation. – littleadv Sep 21 '11 at 05:54
-
Depends on the audience for your documentation - but in some cases you are definitely correct. – Bill Michell Sep 21 '11 at 06: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.) – Péter Török Sep 21 '11 at 07: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 07:13
-
You seem to have misunderstood something. I haven't said I actually ever inherited a good set of unit tests with legacy code. In fact, the only project having *any* unit tests before my arrival is the one I am working on right now. They had about 50 unit tests with 0,6% code coverage when I joined them (for the record, two years later we have over 1700 tests and coverage is a solid 30%). Yes, unit tests can be incorrect in many ways. That's why I wrote "a *good* set of unit tests", sorry if it was unclear. At any rate, documents can be incorrect in at least as many ways as unit tests... – Péter Török Sep 21 '11 at 07:42