我是一个
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.我已经尝试了,但对于较大的项目,它根本不起作用.
