注释

::: 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 标记，每个作者占一行；
姓名与㞨箱地址间隔一个空格；
邮箱地址使用”<>“括起来。
多个作者间不能有空行；

示例：

类注释 ```typescript /**
- 对象 *
- @author 郝洁 haojie@persagy.com
- @author 韩耀龙 */ export class SObject {} ```
接口注释 ```typescript /**
- 命令日志接口 *
- @author 韩耀龙
- */ export interface SICommandLog {} ```

函数

格式：

/**
  * 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 韩耀龙 <han_yao_long@163.com>
 */
export enum STouchState {
    None,       /** 标准状态 */
    Move,       /** 移动状态 */
    Zoom,       /** 缩放状态 */
}

内部注释

待定

comment.md 9.3 KB Permalink History Raw

注释

写注释注意事项

什么时候编写注释

内容要求

注释的合理位置

注释颗料度要求

注释分类

文件头

类与接口注释

函数

属性

枚举

内部注释

comment.md 9.3 KB

Permalink History Raw