Effective Java - 为所有导出的API元素写文档注
作者:
DZQANN | 来源:发表于
2022-08-06 16:25 被阅读0次
第56条 为所有导出的API元素写文档注释
- 为了正确的编写API文档，必须在每个被导出的类、接口、构造器、方法和域声明之前增加一个文档注释
- API文档应该体现以下几点：
- 前提条件(参数需要满足的要求)
@param、@throws
@return
- 同一个类或接口中的两个成员或者构造器，不应该具有相同的概要描述
- 如果代码中出现了泛型，确保要在文档中说明所有的类型参数
- 为枚举类型编写文档时，要确保在文档中说明常量
- 为注解编写文档时，要说明清除所有成员
- 类或者静态方法是否线程安全，应该在文档中进行声明
思考
- 这篇内容明显是为框架开发写的，我们作为框架的使用者其实没有必要做到这么详细
- 对于日常的开发，如果一个方法逻辑相对比较复杂，我会在方法上加上注释，说明入参出参以及大概的逻辑
本文标题：Effective Java - 为所有导出的API元素写文档注
本文链接：https://www.haomeiwen.com/subject/tfnbwrtx.html
网友评论