JUnit测试类中的Javadoc？答案

【问题标题】：Javadoc in JUnit test classes?JUnit测试类中的Javadoc？
【发布时间】：2010-06-03 16:44:31
【问题描述】：

将 Javadoc cmets 放在 JUnit 测试类和方法中是最佳实践吗？还是认为它们应该如此易于阅读和简单，以至于无需提供测试意图的叙述？

【问题讨论】：

您认为如何改用常规的非 Javadoc 块 cmets？代码风格哪个更好？

【解决方案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)

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

【讨论】：

你的例子的输出是什么？
所以当一个测试失败时你运行 test-javadoc 看看它应该做什么？
您在构建过程中运行 test-javadoc 任务。如果测试失败，您的 CI 工具可以将失败的测试链接到生成的 html 页面。这应该比默认的单元测试报告更有帮助，因为它们通常只给你方法名称和预期/实际值，但没有上下文。

【解决方案2】：

我个人很少使用 javadoc cmets，因为我发现它们会增加屏幕上的混乱。如果我能以更自我描述的方式命名一个类、函数或变量，那么我将优先于评论。 Robert C. Martin（又名 Bob 叔叔）的 Clean Code 是一本关于这个主题的优秀书籍。

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

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

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

【讨论】：

现在正在阅读干净的代码。 Roy Ohserov 刚刚完成了单元测试，他非常强调单元和集成测试的人类可读性。

【解决方案3】：

这个问题导致了“代码是需要 cmets 还是必须是自描述的”的永恒圣战。

正如接受的答案中提到的，许多人引用 Rob Martin 作为“代码应该是描述性的，不需要注释”和“不要在公共 API 以外的任何方法上编写 javadocs”的来源。但“干净的代码”不是“绝对真理的圣经”。合理务实的答案是“它总是取决于”。

我个人的喜好是：

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

【讨论】：