某互联网公司前端JS代码规范

JavaScript编程规范

1.概述

    目的：

      规范开发部员工在项目开发过程中的JavaScript编码，进而提高系统性能及代码的可读性，降低维护的难度。

    适用范围：

      使用JavaScript语言开发的所有人员。

2.排版规范

1)      程序块采用缩进风格编写，缩进的空格数为4个，且不要使用TAB键。

说明：

避免使用不同的编辑器或阅读程序时，因TAB键所设置的空格数目不同，而造成程序布局不整齐。

2)      在特定的位置加上空格。

说明：

在特定的位置加上空格有助于代码的可读性,以下位置需要加上空格：

l  算数运算符前后（除累加、递减符）。

l  赋值运算符前后。

l  控制语句关键字之后。（else、catch关键字的前后）。

l  对象初始化的每个属性名的“:“号后。

l  所有“,“号后。

3)     在函数体的开始、类的定义，以及程序块中的语句，需要加上必要的缩进。

说明：

函数和if、for、do、while、switch、case中语句的需要加缩进较长的语句、表达式或参。

示例：

functiondoSomething() {

var a;

}

for (...){

doSomething;

}

4)     较长的语句、表达式或参数要分成多行书写。

说明：

长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进。单行不能超过160个字符。

示例：

if (status == 1

&& (isDelete == null || isDelete ==0)) {

    doSomething;

}

window.open(‘Contract!edit.do’, ‘win_contract_edit’,

‘height=1000,width=600,top=0,left=0');

5)     一行只写一条语句。

说明：

不允许把多个短语句写在一行中.

示例：

var status = 0;

var data = {};

6)     if,for,do,while,case,switch,default等语句自占一行，且执行语句都要被包含在{}。

说明：

不允许在只有一行执行语句的情况下省略｛｝。

示例：

if (status = 1) {

    doSomething;

}

7)     语句必须以“;”号结尾。

说明：

不允许在语句结束后省略“;”号。

示例：

doSomething;

8)     确定不再使用的代码要删除。

说明：

保留不再使用的代码容易在阅读代码的时候对阅读人产生误导，不方便代码阅读。

3.注释规范

1)     全局变量注释。

格式：

    /** 变量的含义、作用 */

说明：

    方便代码阅读及维护。

示例：

/**表单状态 */

var formStatus;

2)     方法注释。

格式：

/**

 * 方法描述、作用

 *@param 参数说明

 *@returns 返回值说明

 */

说明：

方便代码阅读及维护。

示例：

/**

 * 示例方法

 *@param arg示例参数

 *@returns 示例返回值

*/

function doSomething(arg) {

    returnresult;

}

3)     逻辑注释。

格式：

                     //注释内容

说明：

在关键字段和复杂逻辑处添加代码逻辑注释，如if、else、switch等语句。

示例：

//注释

if (status == 1) {

    doSometing;

}

4)     注释与所描述内容进行同样的缩排。

说明：

可使程序排版整齐，并方便注释的阅读与理解。

示例：

/**

 * 示例方法

 *@param arg示例参数

 *@returns 示例返回值

 */

function doSomething(arg) {

    //注释

    returnresult;

}

5)     注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置。

示例：

    //定义新增状态

    var statusNew = 0;

    或

    var statusNew = 0;//定义新增状态

6)     对关键变量的定义和分支语句（条件分支、循环语句等）必须编写注释。

说明：

这些语句往往是程序实现某一功能的关键所在，良好的注释能帮助维护者更好地理解程序，有时甚至优于看设计文档。

示例：

    //如果为新增状态

    if(status = statusNew){

       doSomething;

    }

    //遍历某某数组，进行什么处理

    for(vari = 0; i < arr.length; i++) {

       doSomething;

    }

7)     边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性；不再有用的注释要删除。

8)     注释的内容要清楚、明了，含义准确，防止注释二义性。

说明：

错误的注释不但无益反而有害。

9)     从代码的业务功能、业务意图层次上进行注释。

说明：

注释的目的是解释代码的目的、功能和采用的方法，帮助读者理解代码的业务实现。

示例：

如下注释意义不大。

// 如果状态等于1

if (status === 1)

而如下的注释则给出了业务层面有用的信息。

// 如果是草稿状态

if (status === 1)

 

4.命名规范

命名法：

说明：

    统一命名法有利于代码的可读性，便于维护。

命名法定义：

1、驼峰式：doSomething

2、帕斯卡式：MyObject

3、下划线式：STATUS_NEW

命名约定：

序号	命名对象	命名法	示例
1	全局变量	驼峰式	var contractStatus;
2	函数名	驼峰式	function doSomething(firstArg) {     doSomething; }
3	参数名	驼峰式
4	局部变量	驼峰式	var dataTable;
5	对象	帕斯卡式	function Person(name)  {     this.name = name; }
6	常量	下划线式	var STATUS_NEW = 0;

1)   方法、变量、常量、参数名不超过50字符。

说明：

如果函数名过长时，可采用以去掉元音字母的方法或者以行业内约定俗成的缩写方式缩写函数名。

2)   不实用无意义的方法、变量、常量、参数名。

说明：

属性名使用意义完整的英文描述。

示例：

    规范：

                            var contractStatus;

                     不规范：

                            var a;

3)   含有集合意义的属性命名，需要包含其复数的意义。

示例：

varusers;

varuserList;

4)   各种名称，尽量使用英文单词，减少拼音的使用。

5.编程规范

1)   一个html文件对应一个javascript文件，文件命名与html文件相同。

说明：

在需要进行javascript实现页面逻辑的时候，建立一个与html文件同名的.js文件，若有公用的处理逻辑，应提取到公用的.js中。

2)   禁止在html文件中进行javascript编程。

说明：

若需要接收服务器参数，可以在html中添加javascript代码使用变量接收，但逻辑代码必须写在.js文件中。

3)   一个函数仅完成一件功能，即使简单功能也应该编写方法实现。

说明：

使方法的功能明确化，增加程序可读性，方便维护。

4)   用括号明确表达式的操作顺序，避免使用默认优先级。

说明：

防止阅读程序时产生误解，防止因默认的优先级与设计思想不符而导致程序出错。

示例：

if(条件1 || 条件2 && 条件3)

需写成

if(条件1 || (条件2 && 条件3))

5)   避免使用不易理解的魔术数字，用有意义的常量来替代。

说明：

便于阅读及后期维护。用常量来定义。

示例：

    if(status === 0)

    需写成

    //新增状态

    var statusNew = 0;

    if(status === statusNew)

6)   不要将不同目的的语句，合并成一行。

说明：

便于阅读及后期维护，并且减少编码错误。

              示例：

                     将

var a = b, b = 0;

写成

var a = b = 0;

                     实际上两个表达式的含义是不同的，后者的意思是：

                            var b = 0;

                            var a = b;

7)   所有变量都在使用之前先定义。

说明：

由于javascript的并不强制变量使用前必须定义，但是javascript会将未定义的变量作为全局变量，使得其对于任何一个代码块都是用的。

              示例：

                     规范：

                            var a = 0;

                     不规范：

                            a = 0;

8)   不做大量的html字符串拼接。

说明：

在js中拼接大量的html字符串再动态嵌入html文件中，该做法使得代码可读性及可维护性极差。

              示例：

                     不规范示例：

                     var html = ‘<div id=”div_parent”><div id=”div_child”>……</div></div>’

                     建议大篇幅的html字符穿可以预先写在html文件中隐藏，需要时直接获取该html进行克隆，修改属性后使用。

9)   尽量不写复杂的算法逻辑（比如复杂的递归算法）。

说明：

由于javascript是在客户机上执行，且用户所用的浏览器对脚本的处理能力也不同，复杂的算法可能使得浏览器卡死甚至崩溃。

              示例：

                     不规范示例：

                            function func(arg1){

                                   if(条件1){

                                          doSomething;

                                   } else {

                                          func(arg);

                                   }

                            }

10)  不是用与html节点对象ID属性相同的js变量名称。

说明：

         IE浏览器不支持。

              示例：

                     不规范示例：

                            html：

                                   <input id=”userName” />

                            js：

                       var userName;

11)  不使用模态窗口。

说明：

         统一使用window.open()方法。

12)  尽量使用jquery编程。

说明：

         使用jquery编程会避免一些兼容性问题。