# 注释 ::: details 目录 [[toc]] ::: 注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码。 多行注释规则： * 注释以“/**”开始，以“*/”结尾。 * "/**"与“*/”各占一行; * 每一行注释都以“\*”打头，在“\*”与注释内容之间间隔一个空格； ## 写注释注意事项 ### 什么时候编写注释 修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要及时删除。 ### 内容要求 注释格式尽量统一，使用“/** …… */”形式的注释。 注释语言不统一，影响程序易读性和外观排版。建议多使用中文，不是参与项目的所有人员都能流利的使用英语，出于对维护人员的考虑，建议使用中文。 注释的内容要清楚、明了，含义准确，防止注释二义性。错误的注释不但无益反而有害。 尽量不要使用长句子描述，长句的句法结构过于复杂，不利于维护人员理解。要将长句子分解成多个短句来描述。 避免在注释中使用缩写，特别是非常用缩写。在使用缩写时或之前，应对缩写进行必要的说明。 ### 注释的合理位置 注释应与其描述的代码相近，对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置，不可放在下面。 除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。 类型的声明(包括类、接口、枚举等)，必须加以注释。对类型的注释应放在其上方相邻位置，不可放在下面；对枚举的每个枚举值的注释放在此枚举的上方。 注释与所描述内容进行同样的缩排，让程序排版整齐，并方便注释的阅读与理解。 ### 注释颗料度要求 所有的类、接口、枚举必须编写注释。 类的函数、属性、变量必须写注释。 函数的所有入参、返回值都必须写注释。 所有的分支语句(```if```、```else```、```switch``` 等)、循环语句（```for```、```while```、```do...while``` 等）必须编写注释。 ```switch``` 的每个 ```case``` 分枝都必须写注释。注释写在 ```case``` 语句右端。 对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。 在顺序执行的程序中，每隔3—5行语句，应当加一个注释，注明这一段语句所组成的小模块的作用。对于自己的一些比较独特的思想要求在注释中标明。 注释与其上面的代码用空行隔开。 ## 注释分类 ### 文件头 文件头注释是标识、是旗帜、是团魂。代表了开发团队对所写代码的负责精神。文件头统一使用如下注释： ```typescript /* * ********************************************************************************************************************* * * !! * .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. * * ********************************************************************************************************************* */ ``` ### 类与接口注释 **格式：** ```typescript /** * summary * * @author author-text */ ``` **说明：** * *summary*    简要说明。 * *author-text*    作者描述。描述要包含作者的姓名与邮箱地址。 **风格：** * 作者与简要说明隔一空行； * @author 标识与作者间用 ```tab``` 键完成定位； * 多个作者，使用多个 @author 标记，每个作者占一行； * 姓名与㞨箱地址间隔一个空格； * 邮箱地址使用”<>“括起来。 * 多个作者间不能有空行； **示例：** * 类注释 ```typescript /** * 对象 * * @author 郝洁 * @author 韩耀龙 */ export class SObject {} ``` * 接口注释 ```typescript /** * 命令日志接口 * * @author 韩耀龙 * */ export interface SICommandLog {} ``` ### 函数 **格式：** ```typescript /** * 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 ); } } ``` ### 属性 **格式：** ```typescript /** summary */ ``` **说明：** * *summary*    简要说明。 **风格：** * “/**”、简要说明与“*/”在同一行； * "/**"、简要说明与“*/”之间隔一个空格； * 域属性的注释写在域； * 没有域的属性，写在 ```get``` 操作上； * 没有 ```get``` 操作，写在 ```set``` 操作上； **示例：** ```typescript{2,5,13} 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*    枚举值的简要说明。 **风格：** * 枚举类注释见[类与接口注释](#类与接口注释); * “/**”、枚举值简要说明与“*/”在同一行； * "/**"、枚举值简要说明与“*/”之间隔一个空格； * 枚举值注释写在枚举值上； **示例：** ```typescript{1-5,7,9,11} /** * 手势状态 * * @author 韩耀龙 */ export enum STouchState { None, /** 标准状态 */ Move, /** 移动状态 */ Zoom, /** 缩放状态 */ } ``` ### 内部注释 待定 ```typescript ```