如何编写好的javadoc评论？

发布时间：2020-12-14 16:44:20 所属栏目：Java 来源：网络整理

导读：我是一个 Java开发人员,我有兴趣在我编写的代码和程序中提高我的Javadoc评论的质量,使其更容易理解,更容易让其他开发人员实现. 我已经阅读了许多文章,包括来自官方来源的文章,并尝试遵循本书中所述的指导原则 “The Elements of Java Style”,但尽管如此,并

我是一个 Java开发人员,我有兴趣在我编写的代码和程序中提高我的Javadoc评论的质量,使其更容易理解,更容易让其他开发人员实现.

我已经阅读了许多文章,包括来自官方来源的文章,并尝试遵循本书中所述的指导原则
“The Elements of Java Style”,但尽管如此,并且在广泛地在线搜索之后,似乎找不到一种实用的方式来比较我现有的Javadoc()模型示例并维护Java API文档的最佳实践.

解决方法

同行评审.

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

客户永远是对的.

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

写在javadoc上的一个很好的读者是在http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html的太阳站

从该文本中学到的最好的事情可能是你的类级别的javadoc应该以“提供”开头.这迫使您考虑该课程为您的程序(或世界)提供什么.我重新设计软件并不罕见,因为编写javadoc使我觉得“嘿,这不是必需的！

其他实用提示：当吸气剂很有趣的时候,尝试用@returns标签来写.不这样做可能意味着你输入两次,一次在javadoc中,一次在@return标签之后.

一个最好的提示：如果你不知道写什么,DONT. Javadoc解析器做了很大的工作,例如自动生成getter javadoc,但是只有当您没有添加/ ** * /时,才能执行此操作.

Javadoc应该描述你的方法所做的,而不是.

Javadoc不是你的todolist.我已经尝试了,但对于较大的项目,它根本不起作用.

（编辑：李大同）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!