Note when going straight for success of Mr.Wang

0%

注释规约

注释规约

  1. 类、类属性、类方法的注释必须使用 Javadoc 规范,使用/内容*/格式,不得使用// xxx 方式。**
    reason: 增强可读性(工程调用方法时,不进入方法即可悬浮提示方法、参数、返回值的意义,提高阅读效率。)

  2. 所有的抽象方法(包括接口中的方法)必须要用 Javadoc 注释、除了返回值、参数、异常说明外,还必须指出该方法做什么事情,实现什么功能,对子类的实现要求,或者调用注意事项,也要一并说明

  3. 所有的类都必须添加创建者和创建日期

  4. 方法内部单行注释,在被注释语句上方另起一行,使用//注释。方法内部多行注释使用/ /注释。

  5. 所有的枚举类型字段必须要有注释,要说明每个数据项的用途

  6. 推荐用中文注释把问题说清楚(专有名词与关键字保持英文原文即可)

  7. 代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑等的修改

  8. 不要轻易注释掉代码。后面可能会恢复此段代码逻辑的需在在上方详细说明;如果永久不用的直接删除即可(仓库会保存历史版本代码)。

  9. 要求注释既能够准确反映设计思想和代码逻辑又能够清楚描述业务含义,使自己之后或者别的程序员能够迅速了解代码背后的信息。

  10. 注释力求精简准确、表达到位,而不应过多过滥,不必要可以不写注释(遵守命名格式规范的代码是自解释的)。
    反例:

    1
    2
    // put elephant into fridge
    put(elephant, fridge);
  11. 特殊注释标记并注意及时(通过标记扫描)处理这些标记。线上故障有时候就是来源于这些标记处的代码。
    知识点:TODO和FIXME
    1) 待办事宜(TODO):(标记人,标记时间,[预计处理时间])
      表示需要实现,但目前还未实现的功能。这实际上是一个 Javadoc 的标签,目前的 Javadoc 还没有实现,但已经被广泛使用。只能应用于类,接口和方法(因为它是一个 Javadoc 标签)。
    2) 错误,不能工作(FIXME):(标记人,标记时间,[预计处理时间])
      在注释中用 FIXME 标记某代码是错误的,而且不能工作,需要及时纠正的情况。

-------------the end-------------