Question

Is it a best practice to put Javadoc comments in JUnit test classes and methods? Or is the idea that they should be so easy to read and simple that it is unnecessary to provide a narrative of the test intent?

Answer 1

I personally use javadoc comments sparingly as I find they increase the on-screen clutter. If I can name a class, function or variable in a more self-descriptive way then I will in preference to a comment. An excellent book to read on this topic is Clean Code by Robert C. Martin (a.k.a Uncle Bob).

My personal preference is to make both the class and methods self descriptive i.e.

class ANewEventManager {
   @Test
   public void shouldAllowClassesToSubscribeToEvents() {
        /* Test logic here */
   }
}

One advantage of this approach is that it is easy to see in the junit output what is failing before browsing the code.