comment.md 9.3 KB

注释

::: details 目录 [[toc]] :::

注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码。

多行注释规则:

  • 注释以“/*”开始,以“/”结尾。
  • "/*"与“/”各占一行;
  • 每一行注释都以“*”打头,在“*”与注释内容之间间隔一个空格;

写注释注意事项

什么时候编写注释

修改代码同时修改相应的注释,以保证注释与代码的一致性。不再有用的注释要及时删除。

内容要求

注释格式尽量统一,使用“/** …… */”形式的注释。

注释语言不统一,影响程序易读性和外观排版。建议多使用中文,不是参与项目的所有人员都能流利的使用英语,出于对维护人员的考虑,建议使用中文。

注释的内容要清楚、明了,含义准确,防止注释二义性。错误的注释不但无益反而有害。

尽量不要使用长句子描述,长句的句法结构过于复杂,不利于维护人员理解。要将长句子分解成多个短句来描述。

避免在注释中使用缩写,特别是非常用缩写。在使用缩写时或之前,应对缩写进行必要的说明。

注释的合理位置

注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面。

除非必要,不应在代码或表达中间插入注释,否则容易使代码可理解性变差。

类型的声明(包括类、接口、枚举等),必须加以注释。对类型的注释应放在其上方相邻位置,不可放在下面;对枚举的每个枚举值的注释放在此枚举的右方。

注释与所描述内容进行同样的缩排,让程序排版整齐,并方便注释的阅读与理解。

注释颗料度要求

所有的类、接口、枚举必须编写注释。

类的函数、属性、变量必须写注释。

函数的所有入参、返回值都必须写注释。

所有的分支语句(if、else、switch 等)、循环语句(for、while、do...while 等)必须编写注释。

switch 的每个 case 分枝都必须写注释。注释写在 case 语句右端。

对于维护人员来说,良好的注释帮助更好的理解程序,有时甚至优于看设计文档。

在顺序执行的程序中,每隔3—5行语句,应当加一个注释,注明这一段语句所组成的小模块的作用。对于自己的一些比较独特的思想要求在注释中标明。

注释与其上面的代码用空行隔开。

注释分类

文件头

文件头注释是标识、是旗帜、是团魂。代表了开发团队对所写代码的负责精神。文件头统一使用如下注释:

/*
 * *********************************************************************************************************************
 *
 *          !!
 *        .F88X
 *        X8888Y
 *      .}888888N;
 *        i888888N;        .:!              .I$WI:
 *          R888888I      .'N88~            i8}+8Y&8"l8i$8>8W~'>W8}8]KW+8IIN"8&
 *          .R888888I    .;N8888~          .X8'  "8I.!,/8"  !%NY8`"8I8~~8>,88I
 *            +888888N;  .8888888Y                                  "&&8Y.}8,
 *            ./888888N;  .R888888Y        .'}~    .>}'.`+>  i}!    "i'  +/'  .'i~  !11,.:">,  .~]!  .i}i
 *              ~888888%:  .I888888l      .]88~`1/iY88Ii+1'.R$8$8]"888888888>  Y8$  W8E  X8E  W8888'188Il}Y88$*
 *              18888888    E8888881    .]W%8$`R8X'&8%++N8i,8N%N8+l8%`  .}8N:.R$RE%N88N%N$K$R  188,FE$8%~Y88I
 *            .E888888I  .i8888888'      .:$8I;88+`E8R:/8N,.>881.`$8E/1/]N8X.Y8N`"KF&&FK!'88*."88K./$88%RN888+~
 *            8888888I  .,N888888~        ~88i"8W,!N8*.I88.}888%F,i$88"F88"  888:E8X.>88!i88>`888*.}Fl1]*}1YKi'
 *          i888888N'      I888Y          ]88;/EX*IFKFK88X  K8R  .l8W  88Y  ~88}'88E&%8W.X8N``]88!.$8K  .:W8I
 *        .i888888N;        I8Y          .&8$  .X88!  i881.:%888>I88  ;88]  +88+.';;;;:.Y88X  18N.,88l  .+88/
 *      .:R888888I
 *      .&888888I                                          Copyright (c) 2016-2020.  博锐尚格科技股份有限公司
 *        ~8888'
 *        .!88~                                                                     All rights reserved.
 *
 * *********************************************************************************************************************
 */

类与接口注释

格式:

/**
 * summary
 *
 * @author  author-text
 */

说明:

  • summary

   简要说明。

  • author-text

   作者描述。描述要包含作者的姓名与邮箱地址。

风格:

  • 作者与简要说明隔一空行;
  • @author 标识与作者间用 tab 键完成定位;
  • 多个作者,使用多个 @author 标记,每个作者占一行;
  • 姓名与㞨箱地址间隔一个空格;
  • 邮箱地址使用”<>“括起来。
  • 多个作者间不能有空行;

示例:

函数

格式:

/**
  * summary
  *
  * @param   parameter-name     description
  * @return  return-description
  */

说明:

  • summary

   简要说明。

  • parameter-name

   参数名

  • description

   参数描述

  • return-description

   返回值描述

风格:

  • 入参与出参与简要说明隔一空行;
  • 入参的顺序要与函数的定义保持一致;
  • 入参以有多个,每个入参单独占一行;
  • @param 标识与参数名间用 tab 键完成定位;
  • 多个参数数描述使用 tab 键完成对齐排版;
  • 一个入参有多种类型时,每种类型的描述使用 “|” 分开。注意描述与“|”留至少一个空格。
  • 入参与返回值描述与简要描述之间隔一空行;
  • 函数最多只能有一个 @return 标识。如果函数类的返回类型为 void ,则没有 @return 标识;
  • @return 标识不能排在 @param 标识前边;
  • @return 标识与返回值描述间用 tab 键完成定位;

示例:

  • 有入参与返回值 ```typescript{5-7} export class SRect { /**

    • 生成平移矩形 *
    • @param dx x 轴位移
    • @param dy y 轴位移
    • @return 移动后的矩形 */ translated(dx: number, dy: number): SRect { return new SRect(this.x + dx, this.y + dy, this.width, this.height); } } ```
  • 多类型入参 ```typescript{5-8} export class SRect { /**

    • 构造函数 *
    • @param x x 轴坐标 | 左上角坐标
    • @param y y 轴坐标 | 右下角坐标 | 大小
    • @param width 宽度
    • @param height 高度 */ constructor( x?: number | SPoint, y?: number | SPoint | SSize, width?: number, height?: number ) {} } ```
  • 无返回值 ```typescript{5,6} export class SRect { /**

    • 平移矩形 *
    • @param dx x 轴位移
    • @param dy y 轴位移 */ translate(dx: number, dy: number): void { this.x += dx; this.y += dy; } } ```
  • 只有返回值 ```typescript{5} export class SRect { /**

    • 计算中心点 *
    • @return 中心点坐标 */ center(): SPoint { return new SPoint( this.x + this.width / 2.0, this.y + this.height / 2.0 ); } } ```

属性

格式:

/** summary */

说明:

  • summary

   简要说明。

风格:

  • “/*”、简要说明与“/”在同一行;
  • "/*"、简要说明与“/”之间隔一个空格;
  • 域属性的注释写在域;
  • 没有域的属性,写在 get 操作上;
  • 没有 get 操作,写在 set 操作上;

示例:

export class SRect {
    /** 左上角坐标 */
    leftTop: SPoint;

    /** 矩形的 x 轴坐标 */
    get x(): number {
        return this.leftTop.x;
    }
    set x(value: number) {
        this.leftTop.x = value;
    }

    /** 旋转中心点 */
    private _org = new SPoint():
    get org(): number {
        return this._org;
    }
    set org(value: number) {
        this._org = value;
    }
}

枚举

格式:

  • 枚举类注释 ```typescript /**
    • class-summary *
    • @author author-text */ ```
  • 枚举值注释 typescript /** value-summary */

说明:

  • summary

   简要说明。

  • author-text

   作者描述。描述要包含作者的姓名与邮箱地址。

  • value-summary

   枚举值的简要说明。

风格:

  • 枚举类注释见类与接口注释;
  • “/*”、枚举值简要说明与“/”在同一行;
  • "/*"、枚举值简要说明与“/”之间隔一个空格;
  • 枚举值注释写在枚举值上;

示例:

/**
 * 手势状态
 *
 * @author  庞利祥 <sybotan@126.com>
 */
export enum STouchState {
    None,       /** 标准状态 */
    Move,       /** 移动状态 */
    Zoom,       /** 缩放状态 */
}

内部注释

待定