我是一名Java开发人员,我有兴趣在我编写的代码和程序中提高Javadoc注释的质量,使其更容易理解,更容易让其他开发人员实现.
我已经阅读了很多文章,包括来自官方资源的文章,我尝试遵循"Java风格的元素"一书中所述的指导方针 ,但尽管如此,在网上广泛搜索后,我似乎无法找到将我现有的Javadoc与模型示例进行比较并维护Java API文档的最佳实践的实用方法.
dev*_*per 18
同行评审.
尝试找到团队以外的人(客户)并询问他们对JavaDoc的看法.
顾客永远是对的.
我也可以在下面分享一些东西
有关编写javadoc的精彩内容,请访问 sun网站http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
我从该文本中学到的最好的东西可能是你的类级别javadoc应该以"提供"开头.这会强迫您考虑该类为您的程序(或世界)提供的内容.我重新设计软件并不罕见,因为编写javadoc让我觉得"嘿,这里不需要这个!".
其他实用技巧:当吸气剂很有趣时,尝试在@returns标签中写下它.不这样做可能意味着你输入两次东西,一次在javadoc中,一次在@return标签之后.
最好的提示:如果你不知道写什么,不要.例如,Javadoc解析器在自动生成getter javadoc方面做得很好,但只有当你没有添加/***/时才会这样做.
Javadoc应该描述你的方法做什么,而不是如何.
Javadoc不是你的专业.我已经尝试过,但对于较大的项目,它根本不起作用.