Should JUnit tests be javadocced?

Question

I have a number of JUnit test cases that are currently not documented with Javadoc comments.

The rest of my code is documented, but I'm wondering if it's even worth the effort to document these tests.

Answer 1

I don't find any value in javadocing the test cases. I just make the method name descriptive enough to know the purpose of the test.

In Ruby, I know there are tools to create a document from the name of the tests, but I haven't seen one of these in Java.

Answer 2

I don't see why you should treat test cases any differently than your production code with respect to comments.

Answer 3

Whether javadoc or not, I think that unit tests should definitely be documented. In cases where no formal specification exists, the unit tests are what comes closest to defining the expected behaviour of the code. By documenting the test cases, you will make it very clear to the reader what the test is testing, and why it's testing it.

Answer 4

If the purpose of the test is obvious, I don't bother documenting it.

If it's non-obvious because it deals with some obscure situation - or if I want to refer to a specific bug, for example - in that case I'll add documentation. I don't document exceptions throw etc though - just a quick summary of the method. This happens relatively rarely. I'm more likely to add documentation for helper methods used within multiple tests.

Answer 5

I think it's valuable to javadoc the conditions under which the tests pass.

Answer 6

When thinking about the tests as a documentation, it does not make much sense to "document the documentation". The name of each test should already in itself describe that what is the purpose of the tests - what is the behaviour being specified by that test.

Use long, descriptive names for the tests, and keep the test code as readable as possible.

For example have a look at the test cases in this project. Does any of them do something which is not blatantly obvious by looking at the name of the tests and the test code?

It's only in some rare cases, when the test code is obscure, that comments are needed in tests. For example, if you are testing multi-threaded code and the test code does weird things in order to make sure that the test code runs in the correct order. But even in those cases, a comment is an apology for not writing cleaner test code.

Answer 7

hell yea. even if its just...

create order, edit order, save, load & check it.

if its a really simple test, then maybe not.

I find that as code changes, sometimes the reason for the test is not a obvious as it once was.

Answer 8

Maybe you could get someone who is not entirely familiar with your code to give you some quick feedback as to whether your tests are easily understood as they are.

At the company I work for, we try to give our tests descriptive names and document complexity, but it's often hard to get this "right" with the first draft because things that are obvious to the developer aren't always obvious to others.

Tests are treated like code and are submitted as part of a peer review process so our (small) team can comment as to whether a test is easily understood or not.

If a test is a little confusing, we can update the name or documentation accordingly and we come away with a better gauge of what works and what doesn't.

Answer 9

Is it heresy to suggest that code comments are an anti-pattern? I agree with the above answers, ideally your code would be descriptive enough to rely on without comments. This is especially true if you are in an (enterprise) environment where people tend to update the code without updating comments so comments become misleading.