为单元测试用例编写Java文档注释

在我看来，单元测试用例本身就是代码的文档。我的公司希望我在单元测试用例的顶部编写详细的Java文档注释。是否有必要这样做？你这样写评论吗？

我要做的是JAVADOC评论：

• 该类，指示哪个单元已经过单元测试（尽管我应该很清楚，因为关于该主题的最佳实践表明，测试用例的名称应该是该类的名称+“ Test”或“ TestCase”）。这是通过{@link XXXClass} JAVADOC注释完成的

• 方法，指示要测试的方法（{@link XXXClass＃method1}）。有时我需要为一个类的一个方法使用多种测试方法，以正确测试所有路径。当发生这种情况时，我会另外写一行以说明我正在测试的路径（但我从不偏离我的一线约定）

除此之外，没有其他评论。为了吸引他们的注意力，也许您可​​以使用Cobertura之类的东西来生成漂亮的代码覆盖率图形，并使它们以这种方式高兴:-)

补充说明：我指的是单元测试用例，如果我们谈论的是集成测试用例，那么可能确实需要多一行或两行来说明正在发生的事情...

该问题的答案完全涵盖了任何代码的文档要求：我的老板希望对我们的代码逐行逐行叙述

作为您将在此处看到的答案的摘要，“这取决于您的情况”。在某些情况下，这样做是合理的（并鼓励），而在另一些情况下，则浪费您的时间。

Javadoc注释可以在单独的参考文档中提取和格式化，而单元测试则不能。另外，请记住，用语言写的内容可能与实际代码不同，通常您用语言描述的是实际的预期行为。查找错误的方法之一是将文档与实际代码进行比较（如果它们不匹配）-这是一个错误（在两个错误中，有时在两个错误中）。

单元测试用于测试，而不用于文档。使用单元测试作为文档是错误的，不应该这样做。