当前位置：文江博客话题详情

JUnit 测试类中的 Javadoc？

发布于 2024-09-03 17:21:30 字数 78 浏览 4 评论 0原文

将 Javadoc 注释放入 JUnit 测试类和方法中是否是最佳实践？或者他们的想法是应该易于阅读和简单，以至于没有必要提供测试意图的叙述？

原文

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

逐鹿 2024-09-10 17:21:30

我在测试中经常使用 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)

这是一个相当简单的示例，但是当运行更复杂的测试时，不可能仅使用自描述性方法名称来描述测试。

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.

回复收藏 0 原文

情话墙 2024-09-10 17:21:30

我个人很少使用 javadoc 注释，因为我发现它们会增加屏幕上的混乱。如果我能以更自我描述的方式命名一个类、函数或变量，那么我会优先于注释。关于此主题的一本优秀书籍是 Robert C. Martin 所著的简洁代码（又名鲍勃叔叔）。

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

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

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

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.

回复收藏 0 原文

水染的天色ゝ 2024-09-10 17:21:30

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

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

我个人的偏好是：

当测试很琐碎时，它的名称可以是自我描述的，并且不需要文档。
当测试意味着一些重要的场景时，请在 javadoc 中记录该场景，以便其他开发人员可以在快速帮助中看到它（IntelliJ IDEA 中的 Ctrl + Q），这样他们就可以阅读简单的人类语言文档，而不是阅读复杂的测试代码并理解它的作用。
正如 @Foumpie 的回答中提到的，javadocs 可以生成为 html 文件并与 QA 团队共享，以便他们知道自动测试涵盖的内容，并且不要手动重复相同的工作。
我经常在实现测试之前编写带有测试方法场景的 javadoc，以便在花费大量时间来实现该测试之前有一个完整的计划来了解该测试必须做什么。