Effective Java - 为所有导出的API元素写文档注释

第56条 为所有导出的API元素写文档注释

  1. 为了正确的编写API文档,必须在每个被导出的类、接口、构造器、方法和域声明之前增加一个文档注释
  2. API文档应该体现以下几点:
    • 前提条件(参数需要满足的要求) @param@throws
    • @return
  3. 同一个类或接口中的两个成员或者构造器,不应该具有相同的概要描述
  4. 如果代码中出现了泛型,确保要在文档中说明所有的类型参数
  5. 为枚举类型编写文档时,要确保在文档中说明常量
  6. 为注解编写文档时,要说明清除所有成员
  7. 类或者静态方法是否线程安全,应该在文档中进行声明

思考

  1. 这篇内容明显是为框架开发写的,我们作为框架的使用者其实没有必要做到这么详细
  2. 对于日常的开发,如果一个方法逻辑相对比较复杂,我会在方法上加上注释,说明入参出参以及大概的逻辑

你可能感兴趣的:(Effective Java - 为所有导出的API元素写文档注释)