Menu
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?
778
Adding JavaDoc comments The basic rule for creating JavaDoc comments is that they begin with /** and end with */. You can place JavaDoc comments in any of three different locations in a source file: Immediately before the declaration of a public class. Immediately before the declaration of a public field.
In the Package Explorer view, select a Java project and click Project > Generate Javadoc with Diagrams > Automatically. In the Generate Javadoc wizard, under Javadoc command, select the Javadoc command (an executable file). Note: Only Oracle JDK Version 1.4.
From the main menu, select Tools | Generate JavaDoc. In the dialog that opens, select a scope — a set of files or directories for which you want to generate the reference, and set the output directory where the generated documentation will be placed.
I use Javadoc in my testing a lot. But it only gets really useful when you add your own tag to your javadoc.
The main objective here is to make the test understandable for other developers contributing to your project. And for that we don't even need to generate the actual javadoc.
/** * Create a valid account. * @result Account will be persisted without any errors, * and Account.getId() will no longer be <code>null</code> */ @Test public void createValidAccount() { accountService.create(account); assertNotNull(account.getId()); } Next we'll need to notify our Javadoc plugin in maven that we added a new tag.
<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>2.8</version> <configuration> <tags> <tag> <name>result</name> <placement>a</placement> <head>Test assertion :</head> </tag> </tags> </configuration> </plugin> </plugins> </build> And now all that is left to do is call our maven plugin.
javadoc:test-javadoc (or javadoc:test-aggregate for multi-module projects) This is a fairly easy example, but when running more complex tests, it is impossible to describe the tests by simply using a self-descriptive method name.
61
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.
27
This question leads to eternal holywar of "whether code needs comments or must be self-descriptive".
As mentioned in the accepted answer, many cite Rob Martin as a source of "code should be descriptive and not need a comment" and "do not write javadocs on any methods other that public APIs". But "Clean Code" isn't "A Bible of the Absolute Truth". The reasonable pragmatic answer would be "it always depends".
My personal preference is:
38
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
