Question

我应该为所有java方法编写Doc Comments吗？

Answer 1

@Claudiu

当我编写其他人将使用的代码时 - 是的。其他人可以使用的任何方法（任何公共方法）都应该有一个javadoc，至少说明它的明显目的。

@Daniel Spiewak

我彻底记录了每个API类中的每个公共方法。具有公共成员但不打算用于外部消费的类在javadoc类中突出显示。我还记录了每个API类中的每个受保护方法，但程度较小。这就是为什么任何扩展API类的开发人员都已经对所发生的事情有一个公平的概念。

最后，为了自己的利益，我偶尔会记录私有和包私有方法。我认为在其使用中需要一些解释的任何方法或领域都将收到文档，无论其可见性如何。

@Paul de Vrieze

对于像琐碎的getter和setter这样的东西，在那之间分享评论并描述属性的目的，而不是getter / setter

/** 
 * Get the current value of the foo property.
 * The foo property controls the initial guess used by the bla algorithm in
 * {@link #bla}
 * @return The initial guess used by {@link #bla}
 */
int getFoo() {
  return foo;
}

是的，这是更多的工作。

@VonC

当你将一个巨大的复杂方法（由于high cyclomatic complexity原因）分解为：

一种公共方法调用
几个代表公众内部步骤的私人方法

，javadoc私有方法也非常有用，即使该文档在javadoc API文件中不可见。
尽管如此，它还是让您更容易记住复杂算法不同步骤的精确性。

请记住： limit values or boundary conditions 也应该是您的javadoc的一部分。

另外， javadoc比简单的“// comment” 更好：

它被IDE识别并用于在将光标移动到 - javadoc-ed - 函数之一时显示弹出窗口。例如，常量 - 即私有静态最终变量 - 应该有一个javadoc，特别是当它的值不重要时。一个很好的例子： regexp （它的javadoc应该包含非转义形式的正则表达式，目的是什么以及正则表达式匹配的文字示例）
可以通过外部工具（如xdoclet）

@Domci

对我来说，如果有人会看到它与否并不重要 - 我不太可能知道几个月之后我写的一些不起眼的代码是什么。 [...]
简而言之，评论逻辑，而不是语法，只在适当的地方进行一次。

@Miguel Ping

为了发表评论，你必须先了解它。当你试图评论一个函数时，你实际上正在考虑方法/函数/类的作用，这使你在javadoc中更加具体和清晰，这反过来会让你编写更清晰简洁的代码，这很好

Answer 2

如果该方法明显不言自明，我可以跳过javadoc评论。

像

这样的评论

/** Does Foo */
 void doFoo();

真的没那么有用。（过于简单的例子，但你明白了）

Answer 3

我彻底记录每个API类中的每个公共方法。具有公共成员但不打算用于外部消费的类在javadoc类中突出显示。我还记录了每个API类中的每个受保护方法，但程度较小。这就是为什么任何扩展API类的开发人员都已经对所发生的事情有一个公平的概念。

最后，为了自己的利益，我偶尔会记录私有和包私有方法。我认为在其使用中需要一些解释的任何方法或领域都将收到文档，无论其可见性如何。

Answer 4

对于像琐碎的getter和setter这样的东西，在那之间分享评论并描述属性的目的，而不是getter / setter。

/** 
 * Get foo
 * @return The value of the foo property
 */
int getFoo() {
  return foo;
}

无效。最好做点什么：

/** 
 * Get the current value of the foo property.
 * The foo property controls the initial guess used by the bla algorithm in
 * {@link #bla}
 * @return The initial guess used by {@link #bla}
 */
int getFoo() {
  return foo;
}

是的，这是更多的工作。

Answer 5

其他人已经覆盖的所有基地;另外一个注意事项：

如果您发现自己这样做：

/**
 * This method currently launches the blaardh into the bleeyrg.
 */
void execute() { ... }

考虑将其改为：

void launchBlaardhIntoBleeyrg() { ... }

这似乎有点明显，但在很多情况下，您自己的代码很容易错过机会。

最后请记住，更改不是总是想要的;例如，预计方法的行为会随着时间的推移而发展（请注意JavaDoc中的“当前”一词）。

Answer 6

不，不要评论每个方法，变量，类等。

以下是“清洁代码：敏捷软件工艺手册”的引用：

有一条规则说每个功能都必须有一个，这简直太傻了 javadoc，或者每个变量都必须有注释。像这样的评论只是杂乱无章代码，popagate谎言，并导致一般的混乱和混乱。

当且仅当它为方法，变量，类等的预期用户添加重要信息时，才应存在注释。构成“重要”的内容值得考虑并且可能是当我/如果我回到这个方法/类/等时，提醒自己，方法的后果/副作用，为什么事物甚至存在的动机（在某些代码克服某些缺点/错误的情况下）图书馆或系统），有关表演的重要信息或何时适合打电话等。

什么是不一个好的评论，但表明代码本身应该被重写/修改是一个注释，解释复杂和模糊的方法或功能的细节。相反，更喜欢更清晰的代码。

Answer 7

还有另一个原因你应该使用javadocs。为了发表评论，你必须先了解它。当你试图评论一个函数时，你实际上是思考方法/函数/类的作用，这使你在javadoc中更具体和清晰，这反过来又让你写得更清晰简洁的代码，这很好。

Answer 8

当我为自己编写代码时 - 否。在这种情况下，java doccing是浪费我的时间。

当我编写其他人将使用的代码时 - 是。其他人可以使用的任何方法（任何公共方法）都应该有一个java doc，至少说明它的明显目的。为了一个好的测试 - 在您的代码上运行javadoc创建实用程序（我现在忘记了确切的命令行）。浏览它生成的网页。如果您对使用具有该级别文档的库感到满意，那么您就是金色的。如果没有，在代码中写下更多javadoc 。

Answer 9

对我来说，如果有人会看到它与否并不重要 - 我不太可能知道几个月之后我写的一些不起眼的代码是什么。有一些指导原则：

应彻底评论API，框架类和内部可重用静态方法。
每个复杂代码中的逻辑都应该在两个地方解释 - javadoc中的一般逻辑，以及代码中每个有意义部分的逻辑。
如果模型属性不明显，则应对其进行评论。例如，评论用户名和密码没有意义，但是类型应该至少有一个注释，说明类型的可能值是什么。
我没有记录获取者，制定者或“书中”完成的任何事情。如果团队有一种标准的方式来创建表单，适配器，控制器，外墙......我没有记录它们，因为如果所有适配器都相同并且有一套标准方法则没有意义。任何熟悉框架的人都会知道他们的用途 - 假设框架理念和使用它的方式记录在某处。在这种情况下，评论意味着额外的混乱，没有任何目的。当类做非标准的事情时，有一些例外 - 然后简短评论是有用的。此外，即使我以标准方式创建表单，我也希望将表单的部分内容与简短的注释分开，将代码分成几个部分，例如“结算地址从这里开始”。

简而言之，评论逻辑，而不是语法，只在适当的地方进行一次。

Answer 10

不应该依赖Java文档，因为它会给开发人员带来负担，使他们无法维护java文档和代码。

类名和函数名应该足够明确，以解释发生了什么。

如果要解释一个类或方法的作用使得它的名字太长而无法处理，那么这个类或方法就没有足够的重点，应该重构为更小的单元。

Answer 11

我觉得至少应该对接受的参数和返回类型进行评论。
如果函数名称完全描述了它，可以跳过实现细节，例如 sendEmail（..）;

Answer 12

您可能应该真正记录所有方法。最重要的是公共API方法（尤其是已发布的API方法）。私有方法有时没有记录，虽然我认为它们应该是，为了清楚起见 - 与受保护的方法相同。您的评论应该是提供信息的，而不仅仅是重申代码的作用。

如果方法特别复杂，建议您记录。有些人认为应该清楚地编写代码，以便它不需要注释。但是，这并不总是可行的，因此在这些情况下应该使用注释。

您可以通过代码模板自动为Eclipse中的getter / setter生成Javadoc注释，以节省您必须编写的文档数量。另一个提示是使用@ {$ inheritDoc}来防止接口和实现类之间的代码注释重复。

Answer 13

Javadoc对于库和可重用组件非常有用。但是让我们更实际。拥有自解释代码比javadoc更重要。如果你想象一个带有Javadocs的巨大遗留项目 - 你会依赖它吗？我不这么认为......有人添加了Javadoc，然后实现发生了变化，添加了新功能（删除），因此Javadoc已经过时了。正如我所提到的，我喜欢为库提供javadoc，但对于活跃项目，我更喜欢

小型函数/类，其名称描述了它们的作用
明确单位测试用例，说明了什么函数/类做

Answer 14

简单地说：是

您需要考虑是否应该编写文档的时间，更好地投资于撰写文档。

写一个单行比最好花费时间来完全记录方法。

Answer 15

在以前的公司，我们过去常常使用带有eclipse的jalopy代码格式化程序。这会将javadoc添加到包括private的所有方法中。

它使得记录者和吸气者的生活变得困难。但到底是什么。你必须这样做 - 你做到了。这让我学习了一些XEmacs的宏功能:-)你可以通过编写像几年前ANTLR创建者那样的java解析器和评论者来进一步自动化它： - ）

目前，我记录了所有公共方法以及超过10行的任何内容。

Answer 16

我尝试至少记录每个公共和接口属性和方法，以便调用我的代码的人知道什么是事物。为了维护起见，我也尝试尽可能地排队。即使是我自己为自己做的“个人”项目，我也会尝试javadoc，因为我可以将它搁置一年并稍后再回来。

Answer 17

我认为只要它是非平凡的就写javadoc注释，在使用像eclipse或netbeans这样的IDE时编写javadoc注释并不是那么麻烦。此外，当你写一个javadoc评论时，你不得不考虑这个方法的作用，但是这个方法做什么完全，以及你做出的假设。

另一个原因是，一旦你理解了你的代码并重构了它，javadoc就会让你忘记它的作用，因为你总能引用它。我并不主张故意忘记你的方法，但只是我更愿意记住其他更重要的事情。

Answer 18

你可以对没有javadoc注释的代码运行javadoc，如果你给你的方法和参数提供深思熟虑的名字，它将产生相当可用的javadoc。

Answer 19

到目前为止，假设所有答案都是好评。众所周知，并非总是如此，有时它们甚至是不正确的。如果您必须阅读代码以确定其意图，边界和预期的错误行为，那么缺少评论。例如，方法是线程安全的，任何arg都可以为null，它是否可以返回null等。注释应该是任何代码审查的一部分。

这对私有方法来说可能更为重要，因为代码库的维护者必须应对API用户不会遇到的问题。

也许IDE应该具有允许使用文档表单的功能，以便开发人员可以检查对当前方法重要且适用的各种属性。

您是否为您编写的每种方法使用Javadoc？

19 个答案: