前端编码规范——注释规范

文件申明

顶部添加文件申明信息，包括文件描述、原始作者，如果有更新，则需要添加更新内容、更新作者和更新时间。

/**
 * @description: 说明文字
 * @author: 张三
 */
/**
 * @description: 说明文字
 * @author: 张三
 * @update: 更新内容 by 李四 2013-04-13 18:32
 */

单行注释与多行注释

无论是单行注释还是多行注释，注释中的每一行长度都不能超过 40 个汉字，或者 80 个英文字符。

单行注释
/* this is a short comment */
多行注释
/*
* this is comment line 1.
* this is comment line 2.
*/

函数或方法注释

/**
 * 这是一个求和函数
 * @param  {Number} a 第一个数字
 * @param  {Number} b 第二个数字
 * @return {Number}   返回两个数字之和
 */
var sum = function(a, b) {
    return a + b;
}

模块注释

模块注释必须单独写在一行。

1
2
3

/* 模块：xxxxxx by 张三 */
...
/* 模块：xxxxxx by 张三 */

样式区块注释

/* header */
...
/* footer */
...
/* banner */
...