您编写的每个方法都使用 Javadoc 吗？[关闭]

StackOverflow https://stackoverflow.com/questions/211041

  •  03-07-2019
  •  | 
  •  

题

我应该为我的所有 java 方法编写文档注释吗？

有帮助吗？

解决方案

@克劳迪乌

当我编写其他人会使用的代码时 - 是的。其他人可以使用的每个方法（任何公共方法）都应该有一个 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;
}

是的，这需要更多工作。

@冯C

当你破坏一个巨大的复杂方法时（因为 高圈复杂度 原因）转化为：

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

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

并记住： 极限值或边界条件 也应该是你的 javadoc 的一部分。

加， javadoc 比简单的“//comment”要好得多:

  • 它可以被 IDE 识别，并且当您将光标移动到您的 javadoc-ed 函数之一上时，它会显示一个弹出窗口。例如，一个 持续的 - 那是私有静态最终变量 - 应该有一个javadoc，特别是当它的值不平凡时。例证： 正则表达式 （它的javadoc应该包含非转义形式的正则表达式，目的是什么以及与正则表达式匹配的文字示例）
  • 它可以由外部工具解析（例如 xdoclet)

@Domci

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

@米格尔·平

为了评论某事，你必须先理解它。当你尝试注释一个函数时，你实际上是在思考该方法/函数/类的作用，这使得你的javadoc更加具体和清晰，这反过来又使你写出更清晰和简洁的代码，这很好。

其他提示

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

像

这样的评论 
/** Does Foo */
 void doFoo();

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

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

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

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

是的，这是更多的工作。

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

如果您发现自己这样做：

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

考虑将其改为：

void launchBlaardhIntoBleeyrg() { ... }

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

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

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

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

  

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

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

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

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

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

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

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

  1. 应彻底评论API，框架类和内部可重用静态方法。

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

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

  4. 我没有记录“书籍”中的获取者，制定者或其他任何内容。如果团队有一种标准的方式来创建表单，适配器，控制器，外墙......我没有记录它们，因为如果所有适配器都相同并且有一套标准方法则没有意义。任何熟悉框架的人都会知道他们的用途 - 假设框架理念和使用它的方式记录在某处。在这种情况下，评论意味着额外的混乱，没有任何目的。当类做非标准的事情时，有一些例外 - 然后简短评论是有用的。此外，即使我以标准方式创建表单，我也希望将表单的部分内容与简短的注释分开，这些注释将代码分成几个部分，例如“结算地址从此处开始”。

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

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

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

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

简单地说：是

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

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

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

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

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

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

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

  • 小函数/类，其名称描述了它们的作用
  • 清晰的单位测试用例，可以说明功能/类的功能

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

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

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

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

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

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

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

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

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

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

许可以下： CC-BY-SA 和 归因
不隶属于 StackOverflow
scroll top