# 0.基础
注释的目的：提高代码的可读性，从而提高代码的可维护性
注释的原则：如无必要，勿增注释 ( As short as possible )；如有必要，尽量详尽 ( As long as necessary )
# 一.文件声明
- 定义：顶部添加文件申明信息，包括文件描述、原始作者，如果有更新，则需要添加更新内容、更新作者和更新时间。
- 示例：
//可自行百度,Vscode添加新建文件头部注释
/*
* @Author: hft
* @Date: 2022-03-02 09:29:05
* @LastEditors: hft
* @LastEditTime: 2022-03-11 11:00:54
* @Description: file content
*/
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
# 二.普通注释
- 基础：包括单行注释与多行注释，无论是单行注释还是多行注释，注释中的每一行长度都不能超过 40 个汉字，或者 80 个英文字符。
- 示例：
- 总是在单行注释符后留一个空格
/* this is a short comment */
1
- 总是在多行注释的结束符前留一个空格（使星号对齐）；不要把注释写在多行注释的开始符、结束符所在行
/*
* this is comment line 1.
* this is comment line 2.
*/
/* start
* 不可取
end */
1
2
3
4
5
6
7
2
3
4
5
6
7
- 不要编写无意义的注释
// 初始化value变量为0
var value = 0;
1
2
2
# 三.函数或方法注释
- 模板：
/**
* @method 方法名
* @for 所属类名
* @description 文件、方法描述 描述该功能模块的作用
* @author 作者信息 描述此函数作者的信息
* @version 版本号 描述版本信息
* @param 参数名 {类型} 描述 描述此函数入参的信息
* @return 返回值 {类型} 描述 描述此函数返回的信息
**/
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
说明：
- 没有指定
@for时，表示此函数为全局或模块顶层函数。 - 当函数为静态函数时，必须添加
@static； - 当函数有参数时，必须使用
@param； - 当函数有返回值时，必须使用
@return。 @param,声明函数参数，必须与@method搭配使用。
- 示例：
/**
* 这是一个求和函数
* @param {Number} a 第一个数字
* @param {Number} b 第二个数字
* @return {Number} 返回两个数字之和
*/
var sum = function(a, b) {
return a + b;
};
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# 四.文档注释
- 定义：文档注释将会以预定格式出现在 API 文档中。它以
/**开头，以*/结束，其间的每一行均以*开头（均与开始符的第一个*对齐），且注释内容与*间留一个空格。文档注释必须包含一个或多个注释标签。 - 示例：
/**
* 描述
* @module TestModule
*/
1
2
3
4
2
3
4
# 五.文件声明
- 定义：
@class必须搭配@constructor或@static使用，分别标记非静态类与静态类 - 示例：
/**
* 节点集合类
* @class NodeList
* @constructor
* @param {ArrayLike<Element>} nodes 初始化节点
*/
1
2
3
4
5
6
2
3
4
5
6
# 六.特殊标记注释
- 定义:有时我们发现某个可能的 bug，但因为一些原因还没法修复；或者某个地方还有一些待完成的功能，这时我们需要使用相应的特殊标记注释来告知未来的自己或合作者。
- 模板：
// FIXME: 说明问题是什么
// TODO: 说明还要做什么或者问题的解决方案
1
2
3
2
3
← 03.项目代码管理规范 05.命名规范 →