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