Javadoc in JUnit test classes?_问答_开发者_运维开发者技术经验分享

开发者 https://www.devze.com 2023-01-02 17:41 出处：网络

Is it a best practice to put Javadoc comments in JUnit test classes and methods?Or is the idea that they sho开发者_JS百科uld be so easy to read and simple that it is unnecessary to provide a narrative

相关专题：javadoc junit

Is it a best practice to put Javadoc comments in JUnit test classes and methods? Or is the idea that they sho开发者_JS百科uld be so easy to read and simple that it is unnecessary to provide a narrative of the test intent?

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.

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.

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:

When test is trivial, its name can be self-descriptive and it does not need a doc.
When test implies some non-trivial scenario, document this scenario in the javadoc, so that it can be seen in quick help by other developers (Ctrl + Q in IntelliJ IDEA), so that they can read a simple human-language doc instead of reading the complex test code and understand what it does.
As mentioned in @Foumpie's answer, javadocs can be generated as html files and be shared eg with QA team, so that they know what is covered by auto-tests and do not duplicate the same work manually.
I often write a javadoc with test method scenario before implementing the test, to have a complete plan of what this test has to do before spending some significant time to implement it.