你使用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，类等的预期用户添加重要信息时，评论应该存在。什么构成“重要”值得考虑，并且可以提醒我自己何时/如果我回来到这个方法/类/等，这个方法的一个后果/副作用，为什么这个事物甚至存在的动机（在某些代码克服了某个库或系统的缺点/错误的情况下），关于性能的重要信息或者什么时候适合打电话等等。
什么不是一个好的评论，但代表本身应该重写/修改是一个解释复杂和模糊的方法或函数的细节的评论。 相反，更喜欢更简洁的代码。
对我来说，如果有人会看到或不看重要的东西 – 我不会知道在几个月之后，我写了一些晦涩难懂的代码。 有几条准则：
-
应该对API，框架类和内部可重用的静态方法进行彻底的评论。
-
在每一个复杂的代码段中的逻辑应该在两个地方解释 – javadoc中的一般逻辑和它自己的评论中的每个有意义的代码部分的逻辑。
-
模型属性应该被注释，如果他们不明显。 例如，在评论用户名和密码方面没有任何意义，但types至less应该有一个注释，说明什么types可能的值。
-
我不记载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
