Question

将Javadoc注释放在junit测试类和方法中是最佳做法吗？或者他们认为它们应该如此容易阅读和简单，以至于没有必要提供测试意图的叙述？

Answer 1

我在测试中经常使用Javadoc。但是只有在将自己的标记添加到javadoc时才会非常有用。

这里的主要目标是使其他开发人员能够理解您的项目。为此，我们甚至不需要生成实际的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());
}

接下来，我们需要在maven中通知我们添加了新标签的Javadoc插件。

<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>

现在剩下要做的就是调用我们的maven插件。

javadoc:test-javadoc (or javadoc:test-aggregate for multi-module projects)

这是一个相当简单的示例，但在运行更复杂的测试时，无法通过简单地使用自描述方法名称来描述测试。

Answer 2

我个人谨慎地使用javadoc评论，因为我发现它们增加了屏幕上的混乱。如果我可以用更自我描述的方式命名类，函数或变量，那么我将优先考虑注释。一本关于这个主题的优秀书籍是Robert C. Martin（a.k.a Uncle Bob）的Clean Code。

我个人的偏好是使类和方法都具有自我描述性，即

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

这种方法的一个优点是在junit输出中很容易看到在浏览代码之前失败的内容。

Answer 3

这个问题导致“代码是否需要注释或必须是自描述性的”永恒的战争。

正如接受的答案中提到的那样，许多人将罗布·马丁（Rob Martin）引用为“代码应该是描述性的，不需要注释”和“除了公共API之外，不要在任何其他方法上编写javadocs”。但是“清洁法规”不是“绝对真理的圣经”。合理而务实的答案是“始终取决于”。

我的个人喜好是：

当测试琐碎时，它的名称可以是自描述性的，不需要文档。
当测试暗示一些不平凡的场景时，请在javadoc中记录该场景，以便其他开发人员可以在快速帮助中看到它（ Ctrl + Q IntelliJ IDEA），这样他们就可以阅读简单的人工语言文档，而不必阅读复杂的测试代码并了解其功能。
如@Foumpie's answer中所述，javadocs可以作为html文件生成，并可以与QA团队共享，以便他们知道自动测试涵盖的内容，而不必手动复制相同的工作。
我经常在实施测试之前编写一个带有测试方法场景的javadoc，以便在花费大量时间实施该测试之前，对该测试必须执行的工作有一个完整的计划。

Answer 4

我也喜欢UT中的评论，它有助于在几秒钟内理解用例。

我创建了一个小型库，在任何类型的报告的堆栈跟踪中包含描述，任何正在检查报告的人都可以轻松解决问题。

图书馆名称为Frutilla，随意使用 https://github.com/ignaciotcrespo/frutilla

Junit测试类中的Javadoc？

4 个答案: