52

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

4

19 回答 19

55

@克劳迪乌

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

@丹尼尔斯皮瓦克

我彻底记录了每个 API 类中的每个公共方法。具有公共成员但不供外部使用的类在类 javadoc 中显着标记。我还记录了每个 API 类中的每个受保护方法，尽管程度较轻。这延续了这样一个想法，即任何扩展 API 类的开发人员都已经对正在发生的事情有一个公平的概念。

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

@保罗·德弗里兹

对于诸如琐碎的 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

当您将一个巨大的复杂方法（由于高圈复杂度的原因）分解为：

  • 一种公共方法调用
  • 几种私有方法，代表公共方法的内部步骤

，javadoc 私有方法也非常有用，即使该文档在 javadoc API 文件中不可见。
尽管如此，它仍然可以让您更轻松地记住复杂算法的不同步骤的精确性质。

请记住：限制值或边界条件也应该是您的 javadoc 的一部分。

另外，javadoc 比简单的“//comment”要好得多：

  • 它被 IDE 识别并用于在您将光标移动到您的一个 - javadoc-ed - 函数的顶部时显示一个弹出窗口。例如，一个常量——即私有静态最终变量——应该有一个 javadoc，尤其是当它的值不是微不足道的时候。恰当的例子：正则表达式（它的 javadoc 应该包含非转义形式的正则表达式，目的是什么以及正则表达式匹配的文字示例）
  • 它可以由外部工具（如xdoclet）解析

@Domci

对我来说，如果有人看到它并不重要——几个月后我不太可能知道我写的一些晦涩的代码会做什么。[...]
简而言之，注释逻辑，而不是语法，并且只在适当的地方做一次。

@米格尔平

要评论某事，您必须先了解它。当您尝试注释函数时，实际上是在考虑方法/函数/类的作用，这使您在 javadoc 中更加具体和清晰，从而使您编写的代码更加清晰简洁，这很好.

于 2008-10-17T04:17:03.953 回答
32

如果该方法显然是不言而喻的，我可能会跳过 javadoc 注释。

评论喜欢

/** 是否 Foo */
 无效 doFoo();

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

于 2008-10-17T04:12:12.357 回答
27

我彻底记录了每个 API 类中的每个公共方法。具有公共成员但不供外部使用的类在类 javadoc 中显着标记。我还记录了每个 API 类中的每个受保护方法，尽管程度较轻。这延续了这样一个想法，即任何扩展 API 类的开发人员都已经对正在发生的事情有一个公平的概念。

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

于 2008-10-17T04:08:14.797 回答
15

对于诸如琐碎的 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;
}

是的，这是更多的工作。

于 2008-10-17T08:49:28.443 回答
15

其他人已经覆盖的所有基地；附加说明：

如果你发现自己这样做：

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

考虑将其更改为：

void launchBlaardhIntoBleeyrg() { ... }

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

最后请记住，并非总是需要更改；例如，方法的行为可能会随着时间的推移而发展（注意 JavaDoc 中的“当前”一词）。

于 2008-10-17T23:20:07.263 回答
10

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

这是来自“清洁代码：敏捷软件工艺手册”的引述：

有一个规则说每个函数都必须有一个 javadoc，或者每个变量都必须有一个注释，这简直是愚蠢的。像这样的评论只会弄乱代码，散布谎言，并导致普遍的混乱和混乱。

当且仅当它为方法、变量、类等的预期用户添加重要信息时才应该存在注释。什么构成“重要”值得考虑，并且可以在/如果我回来时提醒自己对于此方法/类/等，该方法的结果/副作用，该事物存在的动机（在某些代码克服某些库或系统的缺点/错误的情况下），有关性能的重要信息或者什么时候适合打电话等等。

不是一个好的注释但表明代码本身应该被重写/修改的是解释复杂和晦涩的方法或函数的细节的注释。相反，更喜欢更短更清晰的代码。

于 2016-10-19T15:25:25.750 回答
6

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

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

于 2008-10-17T06:08:44.990 回答
6

您应该使用 javadocs 还有另一个原因。要评论某事，您必须先了解它。当您尝试对函数进行注释时，您实际上是在考虑方法/函数/类的作用，这使您在 javadoc 中更加具体和清晰，这反过来又使您编写的代码更加清晰简洁，这很好.

于 2008-10-18T15:45:49.647 回答
2

简单地说：是

您需要考虑是否应该编写文档的时间最好花在编写文档上。

写一个单行代码总比花时间根本不记录方法要好。

于 2008-10-17T05:03:32.813 回答
2

对我来说，如果有人看到它并不重要——几个月后我不太可能知道我写的一些晦涩的代码会做什么。有一些指导方针：

  1. API、框架类和内部可重用的静态方法应该被彻底注释掉。

  2. 每一段复杂代码中的逻辑都应该在两个地方解释——javadoc中的一般逻辑，以及代码中每个有意义的部分的逻辑在它自己的注释中。

  3. 如果模型属性不明显，则应对其进行注释。例如，评论用户名和密码没有意义，但 type 至少应该有一个评论，说明 type 的可能值。

  4. 我不记录 getter、setter 或任何“按书”完成的事情。如果团队有创建表单、适配器、控制器、外观的标准方法......我不记录它们，因为如果所有适配器都相同并且具有一组标准方法，那是没有意义的。任何熟悉框架的人都会知道它们的用途——假设框架的理念和使用它的方式记录在某个地方。在这种情况下，评论意味着额外的混乱并且没有任何意义。当类做一些非标准的事情时，这有例外——那么简短的评论很有用。此外，即使我以标准方式创建表单，我也喜欢用简短的注释来划分表单的各个部分，这些注释将代码分成几个部分，例如“帐单地址从这里开始”。

简而言之，注释逻辑，而不是语法，并且只在适当的地方做一次。

于 2008-10-18T09:48:01.677 回答
2

不应依赖 Java 文档，因为它会给开发人员带来负担，因为它需要进行更改以维护 Java 文档和代码。

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

如果要解释一个类或方法的作用使其名称太长而无法处理，则该类或方法的重点不够，应该重构为更小的单元。

于 2013-04-02T15:31:11.537 回答
1

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

于 2008-10-17T07:19:43.180 回答
1

你可能真的应该记录你所有的方法。最重要的是公共 API 方法（尤其是已发布的 API 方法）。私有方法有时没有记录，尽管我认为它们应该记录，只是为了清楚起见——受保护的方法也是如此。您的评论应该提供信息，而不仅仅是重复代码的作用。

如果某个方法特别复杂，建议您将其记录在案。有些人认为代码应该写得很清楚，这样就不需要注释了。然而，这并不总是可行的，因此在这些情况下应该使用注释。

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

于 2009-03-26T01:34:18.063 回答
1

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

  • 具有描述其作用的名称的小函数/类
  • 清晰的单元测试用例解释函数/类的作用
于 2014-10-17T10:20:03.593 回答
0

在以前的公司，我们曾经在 eclipse 中使用 jalopy 代码格式化程序。这会将 javadoc 添加到包括私有在内的所有方法中。

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

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

于 2008-10-17T06:02:41.837 回答
0

我尝试至少记录每个公共和接口属性和方法，以便调用我的代码的人知道它们是什么。为了维护起见，我也尝试尽可能多地发表评论。即使是我在自己的时间为自己做的“个人”项目，我尝试使用 javadoc 只是因为我可能会搁置一年，然后再回来。

于 2008-10-17T23:42:15.457 回答
0

每当写 javadoc 注释不重要时，我都会强调，在使用 Eclipse 或 netbeans 之类的 IDE 时编写 javadoc 注释并不是那么麻烦。此外，当您编写 javadoc 注释时，您不仅要考虑该方法的作用，还要考虑该方法的确切作用以及您所做的假设。

另一个原因是，一旦您理解了代码并对其进行了重构，javadoc 让您忘记它的作用，因为您可以随时参考它。我并不是在提倡故意忘记你的方法做了什么，只是我更喜欢记住其他更重要的事情。

于 2008-10-18T16:22:01.647 回答
0

您可以针对没有 javadoc 注释的代码运行 javadoc，如果您为方法和参数提供周到的名称，它将生成相当有用的 javadoc。

于 2008-10-18T23:32:19.077 回答
0

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

这对于私有方法可能更为重要，因为代码库的维护者将不得不处理 API 用户不会处理的问题。

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

于 2013-05-25T14:09:38.377 回答