如何写出好的javadoc评论？

Question

我是一名Java开发人员，我有兴趣在我编写的代码和程序中提高Javadoc注释的质量，使其更容易理解，更容易让其他开发人员实现。

我阅读了很多文章，包括来自官方来源的文章，我尝试遵循书中所述的指导原则 "The Elements of Java Style"，但尽管如此，在网上广泛搜索后，我似乎找不到一种实用的方法来比较我现有的Javadoc模型示例并维护Java API文档的最佳实践。

Answer 1

同行评审。

尝试找到团队以外的人（客户）并询问他们对您的JavaDoc的看法。

客户永远是对的。

我也可以在下面分享一些东西

关于编写javadoc的精彩内容是在http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

的太阳网站上

我从该文本中学到的最好的东西可能是你的类级别javadoc应该以“提供”开头。这会强迫您考虑该类为您的程序（或世界）提供的内容。我重新设计软件的情况并不少见，因为编写javadoc让我觉得“嘿，这里不需要这个！”。

其他实用技巧：当吸气剂很有趣时，尝试在@returns标签中写下它。不这样做可能意味着你输入两次东西，一次在javadoc中，一次在@return标签之后。

最好的提示：如果你不知道写什么，不要。例如，Javadoc解析器可以很好地自动生成getter javadoc，但只有在你没有添加/ ** * /时才会这样做。

Javadoc应该描述你的方法做什么，而不是如何做。

Javadoc不是你的专业。我已经尝试过，但对于较大的项目，它根本不起作用。

Answer 2

除了http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html的Sun（现在的Oracle）文档之外，我还推荐Joshua Bloch撰写的“Effective Java”一书中的“Item 44: Write doc сomments for all exposed API elements”，第二版。 pp.203-208。这是一个6页的建议/提示，有几个实际的例子。

Answer 3

更好的方法可能是你发布了一个你编写的示例方法，然后我们就可以帮你编写Javadoc了。如果你只是要求提出一般性建议，那么可能很难超越这本书。

Answer 4

您可以将@link参数用于'VoucherStore'

示例：

@return {@link VoucherStore} type Concrete Object based on storeType parameter

而不是

 @return returns VoucherStore type Concrete Object based on storeType parameter.