前端注释说明
注释目的
提高代码的可读性，从而提高代码的可维护性
注释要注意的问题
- 注释是用来消除困惑的不是制造困惑的
- 注释不是代码的简单重复
- 不要写注释去弥补糟糕的代码，直接改代码
- 如果注释写不清楚的话，可能意味着你自己也不理解自己的代码
- 注释也要维护，要及时更新；注释写的不好、维护得不好（比如改了代码没改注释）会导致代码的可读性变差。
好的注释
- 有参考文档的话，可以把地址加上；如果是拷贝的代码的话，把原文件链接加上；如果是修bug的代码要加注释，最好贴上JIRA
- 写注释的时候描述清楚为什么要这样做。代码只会告诉你“这样实现”，而不会告诉你“为什么要这样实现”，而后者比前者更重要。
- 简化代码为一句或两句话，这种注释比重复代码更有价值，能帮助人快速理解代码
糟糕的注释举例：
- 对代码的无脑解释。 printf("%d\n", total_count++); /* 给总计数加1，并打印老的值 */
- 没用但是不愿意删掉的代码。这是滥用注释
- 错误的注释。代码改了，注释没改，误导他人，不如没有
- 无关的注释
前端注释规范
一、哪里要写注释
1，公共代码：
1.1 常量、全局变量和公共类型：必需写注释
1.2 文件注释：
- 如果文件包含多个类/函数，需要在文件开头添加注释，概括文件用途/功能。
- 如果文件仅包含一个导出类/函数，注释需添加在对应类/函数上。
1.3 类/组件：
- 类：在类上方添加注释，概括类的功能。
- 属性：所有public属性必须要写注释。
- 方法: 除以下情况都要写注释
- get/set方法不需要写注释。
- React组件除(willReceive,SCU)外的生命周期不需要写注释。
1.4 函数：
- Export函数必须要写注释，一般函数建议写注释。
2，非公共代码：
2.1 常量、全局变量和公共类型：必需写注释
2.2 业务模块：
- 在目录中的index文件需要描述目录的总体结构及对应业务
2.3 业务组件：
- 在组件的index文件中要描述其对应的业务意义。
3，其它（不区分是否是公共代码）：
- 一些tricky的技巧，一些复杂逻辑，一段骚操作（必需）
- 不合规范的用法（必需）
- TODO，HACK要加注释（必需）
- 在你为某事做了大量工作却无果时，可以把你的心得写下来 （可选）
- 跳过的坑可以写下来，相当于前方高能预警 （可选）
二、注释写法
1，文件开头
用于解释文件的作用；
在源文件最开头注释中写一些使用说明，最好提供一些情况下的 example code；
在目录中的index文件需要描述目录的总体结构及对应业务；
在组件的index文件中要描述其对应的业务意义。
/**
* Describe
*/
2，类
用于解析类的作用；复杂的工具类，最好提供一些情况下的 example code.
/**
* Describe
*/
3，全局变量
用于解析全局变量的作用；
/**
* Describe
*/
4，函数/方法
函数/方法注释必须包含函数说明，有参数和返回值时必须使用注释标识。当 return 关键字仅作退出函数/方法使用时，无须对返回值作注释标识。 参数和返回值不允许省略参数的说明。对于特别复杂的函数，可以注明函数的执行流程。
/**
* 函数描述
*
* @param p1 参数1的说明
* @param p2 参数2的说明，比较长
* 那就换行了.
* @param p3 参数3的说明（可选）
* @return 返回值描述
*/
function foo(p1, p2, p3) {
var p3 = p3 || 10;
return {
p1: p1,
p2: p2,
p3: p3
};
}
/**
* 对于函数参数类型直接写在函数中的情况，也可以写在类型定义中
*
* @param option 参数描述
* @param option.url option项描述
* @param option.method option项描述，可选参数
*/
function foo(option) {
// TODO
}
[建议] 重写父类方法时， 应当添加 @override 标识。如果重写的形参个数、类型、顺序和返回值类型均未发生变化，可省略 @param、@return，仅用 @override 标识，否则仍应作完整注释。
5、常量
用于解释常量的含义；
// Describe
6、类属性
用于解释类属性的含义；
// Describe
7、类型
用于解释类型定义的数据；
// Describe
8、一些复杂逻辑，一段骚操作； 不合语言规范的用法
// Describe
或
/**
* Describe
*/
9、TODO，HACK, WARN要加注释
// TODO: Describe
或
/**
* HACK: Describe
*/
