这是我参与「第五届青训营」笔记创作活动的第8天

前端javascript规范文档

今天开项目，搜了一些前端JS规范，记在下面：

一、规范目的

为提高团队协作效率，便于前端后期优化维护，输出高质量的文档。

二、基本准则

符合web标准，结构表现行为分离，兼容性优良。页面性能方面，代码要求简洁明了有序，尽可能的减小服务器负载，保证最快的解析速度。
项目的维护和二次开发可能是直接或间接的团队合作，所以创建易维护的代码是一个项目成功与否的关键，易维护的代码意味着具有如下特性：
- 阅读性好：如良好的注释和命名规范，有文档
- 具有一致性：看起来如同一个人编写
- 代码的松耦合，高度模块化：将页面内的元素视为一个个模块，相互独立，尽量避免耦合过高的代码，从html,css,js三个层面都要考虑模块化
- 严格按照规范编写代码

三、命名规范

1. 目的

提高代码可预测性和可维护性的方法是使用命名约定，这就意味着采用一致的方法来对变量和函数进行命名。

2. 变量名

变量名包括全局变量，局部变量，类变量，函数参数

3. 构造函数（类）命名

首字母大写，驼峰式命名。

JS中没有类，但是可以用new调用构造函数：var man = new Person();

4. 普通变量命名

首字母小写，驼峰式命名，匈牙利命名

如：nCheckCount 表示整形的数值

例如：

function fnGetNumber(nTotal) {
    if (nTotal < 100) {
        nTotal = 100;
    }
    return _fnAdd(nTotal);

    function _fnAdd(nNumber) {
        nNumber++;
        return nNumber;
    }
}
alert(fGetNumber(10)); //alert 101

对象方法与事件响应函数：对象方法命名使用fn+对象类名+动词+名词形式；

例如： fnAddressGetEmail()，

事件响应函数：fn+触发事件对象名+事件名或者模块名

例如：fnDivClick()，fnAddressSubmitButtonClick()

四、编写注释

为代码编写注释是非常重要的。通常人们在深入思考一个问题时，会非常清楚这段代码的工作原理。但是当过一周后再次回到该代码时，可能会花上很长时间来回想起那段代码到底是干什么的。

公共组件维护者和各栏目WD都需要在文件头部加上注释说明：

/**
*文件用途说明
*作者姓名、联系方式（旺旺）
*制作日期
**/

大的模块注释方法：

//================
// 代码用途
//================

小的注释；
```
//代码说明
```
注释单独一行，不要在代码后的同一行内加注释。例如：
```
//姓名
var name = “abc”;   V
var name =”abc”; //姓名 X
```

五、使用空格

使用空格有助于改善代码的可读性和一致性。在撰写英文文章时在逗号和区间范围后面使用空格。在javascript采用同样的逻辑，可在列表表达式（等价于逗号）和语句结束（等价于完成一次“思考”）后面添加空格。

用处一

在分开for循环的各个部分的分号之后：例如，for (var i = 0; i < 10; i +=1){…}
在for循环中初始化多个变量（i和最大值等）：for (var i = 0, max = 10; i < max; i += 1){…}
在限定数组项的逗号后面：var a = [1, 2, 3];
对象属性的逗号之后和将属性名和属性值分开的冒号之后：var o = {a: 1, b: 2};
分隔开函数中各个参数的逗号之后：myFunc(a, b, c)
在函数声明的大括号之前：function myFunc() {}
在匿名函数表达式之后：var myFunc = function () {};

用初二

空格的另外一个很好的用途是用来分隔所有的操作符和操作，这也就是意味着在 +, -, *, =, <, >, <=, >=, ===, !==, &&, ||, += 等之后使用空格：

例子：

//大量空格，并且使用一致，是的代码可读性更好
//允许在阅读的时候不用一口气读下去
var d = 0,
    a = b +1;
if ( a && b && c) {
    d = a % c;
    a += d;
}

//反模式
//缺少空格或空格使用不一致，使得代码比较混乱
var d= 0;
    a =b+1;
if (a&& b&& c) {
d=a %c;
    a+= d;
}

六、编写API文档

1. 生成API文档的步骤：

编写特殊格式的代码块（即一些注释块）
运行工具来解析代码和注释（工具如：JSDoc Toolkit和YUIDoc）
发布工具解析的结果，大多数情况是采用HTML格式发布（如网页版的API文档就是利用工具生成的）

简单举例：

/**
* 翻转一个字符串
*
* @param  {String} 输入需要翻转的字符串
* @return {String} 翻转后的字符串
**/

var reverse = function (input) {
    return output;
};

前端与JS规范 | 青训营笔记