如何写出好的javadoc注释？
我是一名 Java 开发人员，我有兴趣提高我编写的代码和程序中的 Javadoc 注释的质量，以使其更容易理解，更容易被其他开发人员实现。
我读过很多文章，包括来自官方来源的文章，并且我尝试遵循书中规定的指南 “Java 风格的元素”，但尽管如此，在网上广泛搜索后，我似乎无法找到一种实用的方法来将我现有的 Javadoc 与模型示例进行比较并维护 Java API 文档的最佳实践。
I am a Java developer, and I'm interested in improving the quality of my Javadoc comments in the code and programs I write to make it more comprehensible and easier for other developers to implement.
I've read lots of articles, including those from official sources, and I try to follow the guidelines stated in the book
"The Elements of Java Style", but despite this, and after searching extensively online, I can't seem to find a practical way to compare my existing Javadoc(s) to model examples and maintain best practices for Java API documentation.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（3）
同行评审。
尝试找到团队之外的人（客户）并询问他们对您的 JavaDoc 的看法。
顾客永远是对的。
我还可以在下面与您分享一些内容
关于编写 javadoc 的精彩读物位于 sun 站点 http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
我从该文本中学到的最好的东西可能是您的类级别 javadoc 应该从“提供”开始。这迫使您思考该类为您的程序（或世界）提供了什么。对我来说重新设计软件并不罕见，因为编写 javadoc 让我想“嘿，这里不需要这个！”。
其他实用技巧：当 getter 有趣时，尝试将其写在 @returns 标记中。不这样做可能意味着您需要输入两次内容，一次在 javadoc 中，一次在 @return 标记之后。
最好的提示：如果您不知道该写什么，那就不要写。例如，Javadoc 解析器在自动生成 getter javadoc 方面做得很好，但只有在您没有添加 /** */ 时它才会这样做。
Javadoc 应该描述你的方法做了什么，而不是如何做。
Javadoc 不是您的待办事项列表。我已经尝试过，但对于较大的项目，它根本不起作用。
Peer review.
Try and find someone outside your team (a customer) and ask them what they think about your JavaDoc.
The customer is always right.
Also i can share you some stuff below
A great read on writing javadoc is at the sun site at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
The best thing I've learned from that text is probably that your class level javadoc should start with "Provides". This forces you to think about what that class provides to your program (or the world). It's not uncommon for me to redesign software because writing javadoc made me think "hey, this is not needed here!".
Other practical tips: When a getter is interesting, try to write it in the @returns tag. Not doing so might mean that you type stuff twice, once in the javadoc, and once after the @return tag.
An the best tip: If you don't know what to write, DONT. the Javadoc parser does a great job of automatically generating getter javadoc for example, but it only does it when you didn't add a /** */.
Javadoc should desccribe WHAT your method does, not HOW.
Javadoc is not your todolist. I've tried it, but for larger projects, it simply doesn't work.
除了位于 http:// 的 Sun（现在的 Oracle）文档之外www.oracle.com/technetwork/java/javase/documentation/index-137868.html 我会推荐“第 44 项：为所有公开的 API 元素编写文档注释”来自“Effective Java”一书作者：约书亚·布洛赫，第二版。第 203-208 页。这是一个 6 页的推荐/提示，其中包含几个实际示例。
In addition to the Sun's (now Oracle) documentation at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html I would recommend the "Item 44: Write doc сomments for all exposed API elements" from the "Effective Java" book by Joshua Bloch, 2nd ed. pp.203-208. This is a 6 page recommendation/tips with several practical examples.
您可以将
@link参数用于“VoucherStore”示例：
而不是
You can use
@linkparameter for 'VoucherStore'Example:
instead of