如何编写好的Javadoc注释? [英] How to write good javadoc comments?

问题描述

我是Java开发人员，我对提高我编写的代码和程序中Javadoc注释的质量感兴趣，以使其他开发人员更容易理解和实现它.

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.

我已经阅读了许多文章，包括来自官方的文章，并且我尝试遵循书中所述的准则 "Java风格的元素" ，但是尽管如此，并且在网上进行了广泛搜索之后，我还是似乎找不到一种实用的方法来比较我现有的Javadoc和模型示例并维护Java API文档的最佳做法.

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.

推荐答案

同行评审.

尝试找到团队之外的人(客户)，并询问他们对JavaDoc的看法.

Try and find someone outside your team (a customer) and ask them what they think about your JavaDoc.

顾客永远是对的.

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

Also i can share you some stuff below

Sun网站上的 http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

从该文本中学到的最好的东西可能是您的类级别的javadoc应该以"Provides"开头.这迫使您考虑该类为您的程序(或整个世界)提供了什么.重新设计软件对我来说并不罕见，因为编写javadoc使我觉得嘿，这里不需要！".

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!".

其他实用技巧:当吸气剂很有趣时，请尝试在@returns标记中编写它.不这样做可能意味着您键入了两次，一次在javadoc中，一次在@return标记后.

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.

最好的提示:如果您不知道写什么，请不要.例如，Javadoc解析器在自动生成getter javadoc方面做得很好，但是只有在您未添加/** */时，它才会这样做.

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应该描述您的方法做什么，而不是方法.

Javadoc should desccribe WHAT your method does, not HOW.

Javadoc不是您的待办事项列表.我已经尝试过了，但是对于较大的项目，它根本行不通.

Javadoc is not your todolist. I've tried it, but for larger projects, it simply doesn't work.

这篇关于如何编写好的Javadoc注释?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！