你使用Javadoc你写的每一个方法?

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

@Claudiu

当我写代码,其他人将使用 – 是的。 其他人可以使用的任何方法(任何公共方法)都应该有一个javadoc,至less说明其明显的目的。

@Daniel Spiewak

我彻底logging每个API类中的每个公共方法。 有公共成员,但不打算用于外部消费的类在javadoc类中显着标记。 我还logging了每个API类中的每个受保护的方法,尽pipe程度较低。 这就意味着任何扩展API类的开发人员都已经有了一个公平的概念。

最后,为了我自己的利益,我会偶尔logging私人和私人包装的方法。 任何我认为需要某种解释的方法或领域将会收到文件,无论其可见性如何。

@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

当你将一个巨大复杂的方法(由于高复杂度原因)分解为:

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

,javadoc私有方法也是非常有用的,尽pipe这些文档在javadoc API文件中是不可见的。
不过,它还允许您更容易地记住复杂algorithm不同步骤的确切性质。

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

另外, javadoc比简单的“//评论”更好

  • 它被IDE识别,用于在将光标移动到其中一个 – javadoc-ed – 函数的顶部时显示popup窗口。 例如, 常量 – 即私有静态最终variables – 应该有一个javadoc,特别是当它的值不是微不足道的时候。 例如: regexp (它的javadoc应该包含非转义forms的正则expression式,目的是什么和正则expression式匹配的文字示例)
  • 它可以被外部工具parsing(如xdoclet )

@Domci

对我来说,如果有人会看到或不看重要的东西 – 我不可能知道在几个月之后,我写了一些不太重要的代码。 […]
总之,评论的逻辑,而不是语法,只做一次,在一个适当的地方。

@米格尔·平

为了评论某些东西,你必须首先了解它。 当你试图评论一个函数的时候,你实际上是在想方法/函数/类是干什么的,这使得你在javadoc中更加具体和清晰,这又使得你写出更清晰简洁的代码,这是很好的。

如果这个方法显然是不言而喻的,我可能会跳过一个javadoc的评论。

  / **是否Foo * /
  void doFoo();

真的没有那么有用。 (过于简单的例子,但你明白了)

彻底logging每个API类中的每个公共方法。 有公共成员,但不打算用于外部消费的类在javadoc类中显着标记。 我还logging了每个API类中的每个受保护的方法,尽pipe程度较低。 这就意味着任何扩展API类的开发人员都会对发生的事情有一个公平的概念。

最后,为了我自己的利益,我会偶尔logging私人和私人包装的方法。 任何我认为需要某种解释的方法或领域将会收到文件,不pipe其可见性如何。

对于像平凡的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中的“当前”一词)。

当我为自己写代码 – 没有 。 在这种情况下,java doccing是浪费我的时间。

当我写代码,其他人将使用 – 是的 。 其他人可以使用的任何方法(任何公共方法)都应该有一个java文档,至less要说明其明显的目的。 对于一个好的testing – 在代码上运行javadoc的创build工具(我现在忘了确切的命令行)。 浏览它生成的网页。 如果你能满意地使用具有这种文档级别的图书馆,那么你就是个好人。 如果不是,请在代码中写入更多javadoc

还有一个原因,你应该使用javadocs。 为了评论某些东西,你必须首先了解它。 当你试图评论一个函数的时候,你实际上是在方法/函数/类是干什么的,这使得你在javadoc中更加具体和清晰,这又使得你写出更清晰简洁的代码,这是很好的。

不,不要评论每个方法,variables,类,等等。

这里有一个“清洁代码:敏捷软件工艺手册”的引用:

有一个规则说,每个函数都必须有一个javadoc,或者每个variables都必须有一个注释,这显然是愚蠢的。 像这样的评论只是把代码搞糊涂了,放肆的谎言,借给一般的混乱和混乱。

如果且仅当为方法,variables,类等的预期用户添加重要信息时,评论应该存在。什么构成“重要”值得考虑,并且可以提醒我自己何时/如果我回来到这个方法/类/等,这个方法的一个后果/副作用,为什么这个事物甚至存在的动机(在某些代码克服了某个库或系统的缺点/错误的情况下),关于性能的重要信息或者什么时候适合打电话等等。

什么不是一个好的评论,但代表本身应该重写/修改是一个解释复杂和模糊的方法或函数的细节的评论。 相反,更喜欢更简洁的代码。

对我来说,如果有人会看到或不看重要的东西 – 我不会知道在几个月之后,我写了一些晦涩难懂的代码。 有几条准则:

  1. 应该对API,框架类和内部可重用的静态方法进行彻底的评论。

  2. 在每一个复杂的代码段中的逻辑应该在两个地方解释 – javadoc中的一般逻辑和它自己的评论中的每个有意义的代码部分的逻辑。

  3. 模型属性应该被注释,如果他们不明显。 例如,在评论用户名和密码方面没有任何意义,但types至less应该有一个注释,说明什么types可能的值。

  4. 我不记载getter,setter或任何“按书”所做的事情。 如果团队有创build窗体,适配器,控制器,外墙的标准方式…我不logging它们,因为如果所有适配器都是相同的并且有一套标准方法,那么没有意义。 任何熟悉框架的人都会知道他们是干什么的 – 假设框架的理念和使用方式都被logging在某个地方。 在这种情况下,评论意味着更多的混乱,没有任何目的。 有一些例外,当类做非标准的东西 – 然后短评论是有用的。 另外,即使我以标准方式创build表单,我也喜欢用简短的注释来划分表单的各个部分,这些注释会将代码分成几个部分,例如“帐单地址从这里开始”。

总之,评论的逻辑,而不是语法,只做一次,在一个适当的地方。

不应该依赖Java文档,因为它会给开发人员带来一些负担,使开发人员对Java文档以及代码进行更改。

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

如果要解释一个类或方法的名称太长而不能处理,那么这个类或方法就不够集中,应该被重构成更小的单元。

简单地说:是的

你需要考虑是否应该写一个文档的时候,最好是写一个文档。

写一个单一的内容比花时间最后不logging这个方法要好。

我觉得至less应该对所接受的参数和返回types进行评论。
可以跳过实现细节,以防函数名称完全描述它,例如sendEmail(..) ;

你应该logging所有的方法。 最重要的是公共API方法(特别是公布的API方法)。 私有方法有时没有logging,尽pipe我认为它们应该是,为了清楚起见 – 与受保护的方法一样。 您的意见应该是信息丰富的,而不只是重申代码的作用。

如果某种方法特别复杂,build议您将其logging下来。 有些人认为,代码应该写的很清楚,不需要评论。 但是,这并不总是可能的,所以在这些情况下应该使用注释。

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

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

这使得制定者和获得者难以logging。 但是什么。 你必须这样做 – 你这样做。 这让我学习了XEmacs的一些macrosfunction:-)通过编写一个像ANTLR创build者这样的javaparsing器和评论者,你可以进一步实现自动化:-)

目前,我logging所有公共方法和任何超过10行。

我认为只要不重要就写javadoc注释,在使用像eclipse或netbeans这样的IDE时编写javadoc注释并不麻烦。 另外,当你写一个javadoc评论的时候,你不得不考虑这个方法做了什么,但是这个方法到底做了什么 ,以及你做出的假设。

另一个原因是,一旦你理解你的代码并重构它,javadoc允许你忘记它的作用,因为你总是可以引用它。 我并不主张故意忘记你的方法,而只是我更愿意记住其他更重要的事情。

您可以针对没有javadoc注释的代码运行javadoc,如果您为方法和参数提供深思熟虑的名称,则会生成相当可用的javadoc。

我尽量至lesslogging每个公共和接口的属性和方法,以便调用我的代码的人知道什么是事物。 为了维护的目的,我也尽可能地对其进行评论。 即使是我自己的时间里为自己做的“个人”项目,我也会尽力去做,因为我可能会搁置一年,然后再回来。

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

对于私有方法来说,这可能更为重要,因为代码库的维护者将不得不面对API用户不会遇到的问题。

也许IDE应该有一个允许使用logging表单的特性,以便开发人员可以检查对当前方法来说重要和适用的各种属性。

Javadoc对于库和可重用组件非常有用。 但让我们更实际。 拥有自我解释的代码比javadoc更重要。 如果你想象一个与Javadocs一个巨大的遗留项目 – 你会依靠吗? 我不这么认为…有人添加了Javadoc,然后实现发生了变化,新的function被添加(删除),所以Javadoc已经过时了。 正如我所提到的,我喜欢为图书馆提供javadocs,但对于活跃的项目我更喜欢

  • 小函数/类名称描述他们做什么
  • 明确的unit testing用例给出解释function/类的function