前端代码编码和设计规范系列——JavaScript编程规范

1文档信息

条目	内容
项目编号	通用
项目名称	通用
标题	JavaScript编程规范
类别	规范文档
当前	试用草稿
摘要
当前版本	V1.0
日期	2015/11/9
作者	徐维坚（xuweijian）
文档拥有者	内部公开
文件	前端规范系列-JavaScript篇.docx

2修改历史

编号	修订人	修订内容简述	修订 日期	修订前 版本号	修订后 版本号
V0001	徐维坚	编程规范文件编写，草稿试用版公布	2015/11/10		V1.0

规范前言

良好的编程规范对于软件的开发与维护，至关重要！他不仅可以提高代码的可读性、可靠性、有效性、健壮性，而且利于帮助开发人员开发和维护代码。对于一个团队协作的项目来说，人员的变动，一个良好的编程规范，有助于后续开发者和新手快速了解项目代码所要表现的含义。

1 范围   

本规范规定了使用JavaScript语言编程时排版、命名、声明、作用域、及一些特殊符号的规则和建议。  

本规范适用于使用JavaScript语言编程的产品和项目。 

2 术语和定义  

规则：编程时强制必须遵守的原则。 

建议：编程时必须加以考虑的原则。  

格式：对此规范格式的的说明。 

说明：对此规范或建议进行必要的解释。 

实例/如：对此规范或建议从正、反两个方面给出的例子。

1命名规范

1.1基本规则

规范的命名能使程序更易阅读，从而更易于理解。它们也可以提供一些标识功能方面的信息，有助于更好的理解代码和应用。
1）      规则一：使用可以准确说明变量、函数、原型(prototype)的完整英文描述符。严禁使用汉语拼音、不相关单词及汉字进行命名，实例：firstName，listAllUsers或 CorporateCustomer等；

2）      规则二：尽量少用缩写，但如果一定要使用或名称过长（不超过 25 个字母），当使用公共缩写和习惯缩写等，如实现（implement）可缩写成impl，经理（manager）可缩写成mgr等，严禁滥用缩写；

3）      规则三：变量命名必须以小写字母开头，命名使用骆峰命名规则；

4）      规则四：方法名必须使用动词或动词短语命名，实例：getIdcName()、export()等；

5）      规则五：避免使用相似或者仅在大小写上有区别的名字，以免不严格区分大小写的系统视为同一名称；

6）      规则六：避免命名中含有数字，但可以用2表示to，4表示for，另末尾使用数字表示同一系列的除外，如var$td_1 = $(‘.grid td’)[1];

7）      规则七：类名、构造函数、公共对象实例等名称首字母大写。

var MyCommon = {     getSmallClassFromBigClass: function() {} }

 

1.2相关建议

以下为相关建议，非必要遵循，但需要考虑

1)      建议一：变量如果设置为私有变量，函数为私有函数，则前面添加下划线进行标注；公有变量和函数不添加下划线

实例一： var MyClass = function() { var _thisTotal = 0; var _doSomething = function() {}; this.getThisTotal = function() {     return _thisTotal; }; }; var myClassInstance = new MyClass(); myClassInstance.total = myClassInstance. getThisTotal();

实例二： function MyClass() { this._thisTotal = 0; this._doSomething = function() {}; } MyClass.prototype.getThisTotal = function() {     return this._thisTotal; }; var myClassInstance = new MyClass(); myClassInstance.total = myClassInstance.getThisTotal();

2)      建议二：前面加"is" 的变量名应该为布尔值，同理 "has","can" 或者 "should"亦如此；

3)      建议三：重复变量建议使用"i", "j", "k" （依次类推）等名称的变量；

4)      建议四：全局变量、常量应该全部大写；

5)      建议五：术语"initialize" 或者 "init" 作为变量名应为已经实例化（初始化）完成的类或者其他类型的变量；为函数，应为初始化操作。

2代码组织规范

基本原则：利于个人开发，便于相互交流。
【说明】：因个人习惯和编辑器等可以设置而形成自己独特的风格，但必须前后一致，并符合本规范的基本规则、建议和格式。

2.1缩排

原则：

（1）代码中以TAB（4个字符）缩进，在编辑器中请将TAB设置为相同的长度，否则在不同编辑器或设置下会导致TAB长度不等而影响整个程序代码的格式；

（2）同一代码块中的代码对齐，这里所说的代码块，包括但不限于：function、if else语句、while、for等，即使
c8fb
用{}包围的代码。

2.1注释

原则：不吝惜代码注释，重要函数、变量必须添加注释；特殊函数、变量、常量必须添加注释。

注释的格式，可参考如下所示：

1）变量注释：

// 初始化序列号 var index = 0;

var index = 0; // 初始化序列号

 

2）函数注释，包括a.函数描述及其功能说明；b.参数描述应包括类型、参数名、参数描述；有返回值的需要对返回值进行相应描述：

/** * 绑定事件      * @param  {Object} $detailDom 当前变更详情页面主体DOM对象      * @return null      */ function _bindEvent($detailDom) {

/**      * 查看专线详情      * @param  {jQueryObject} $grid    列表DOM容器      * @param  {String} selector 需要添加详情链接的选择器      * @param  {Boolean} needSpecialId 是否需要指定其他特定id，默认不传，即false      * @param  {String} specialIdName needSpecialId为true，此值必传，即指定id的属性名称      * @return {Boolean} result 操作是否成功      */     viewDetail: function($grid, selector, needSpecialId, specialIdName) {         var self = this;

 

3）文件注释，应该包含文件描述、功能简介和作者，还可以加上创建时间：

/**  * 本js实现专线续费申请页面所有功能 * @author xuweijian  * @date 2015/10/12 15:25:33  */ $(function() {

 

4）行注释与块注释：使用 //…的注释方法来注释需要表明的内容；使用/**和*/注释的方法来注释需要表明的内容。

3 编码规范

3.1 变量编码规范

原则：在遵循命名规则之上，应遵守以下规则，

（1）申明多个变量，变量之间使用逗号分隔；同时建议逗号与变量之间添加一个空格，避免过于拥挤，或是换行申明（此时可以对某个变量添加注释！），

实例一： var name = ‘’, value = ‘’, title = ‘’;

实例二： var name = ‘’, value = ‘’, // 注释 title = ‘’;

 

（2）变量申明时，应明确变量的类型，可以立即赋值，尽量避免变量的类型在使用过程中被转换；

（3）尽量避免魔数（Magicnumbers），他们应该使用常量来代替；

（4）声明变量必须加上 var 关键字，否则将成为全局变量（Document或者 Window），进而成为污染全局的变量；

3.2 函数编码规范

原则：

（1）       所有的函数在使用前进行声明，内函数的声明跟在var 语句的后面；

（2）       不要在语句块（if…else等）内声明一个函数；

 

其编码风格应该遵循这几点建议：

1）  建议一：函数名与参数()之间不要留有空格；

2）  建议二：参数列表之间使用逗号分隔，逗号与参数之间留有一个空格；

3）  建议三：使用右侧简约模式，)与{之间留一个空格；

4）  建议四：避免参数过多现象，一般不超5个，过多使用对象传入；

5）  建议五：匿名函数不应该换行，如：$(‘#id’).bind(function(){…});中参数为匿名函数不应该换行处理，函数的主体遵循前面建议与原则；

 

function outer(c，d) { var e = c * d; function inner(a， b) { return (e * a) + b; } return inner(0， 1); }

// 简约模式 function outer(c，d) { var e = c * d; function inner(a， b) { return (e * a) + b; } return inner(0， 1); }

 

       在函数体中，我们应遵循以下建议：

1）建议一：避免提供多个出口；

//不要使用这种方式，当处理程序段很长时将很难找到出口点 if (condition) { return A; } else { return B; }

//建议使用如下方式 var result = null; if (condition) { result = A; } else { result = B; } return result;

 

2）建议二：函数体中代码不应过长，一般不要超过100行；

3.3表达式与语句

原则：表达式和语句应清晰、简洁，易于阅读和理解，避免使用晦涩难懂的语句。使用圆括号明确表达式执行优先级。

3.3.1控制语句

1）建议一：判断中如有常量，则应将常量置与判断式的右侧。如：

if ( true == isAdmin())... if ( null == user)...

2）建议二：boolean类型判断语句尽量明确条件比较值true/false

//不建议使用 if (isCond)... if (!isCond)...

//尽量使用 if (true == isCond)… if (false == isCond)… if (true != isCond)…

 

       编码风格应遵循以下建议：

（1）       建议一：if…else if…else语句必须使用{}将每个判断条件后的执行语句括起来。

（2）       建议二：if…else if…else与小括号、大括号之间应该空一格；

（3）       建议三：条件中的变量与“==”、“===”之间应该空一格；

（4）       建议四：类型确定的变量，在比较时，应使用严格相等符“===”，即”0” ===0比较值是false。

3.3.2循环语句

原则：

（1）       循环中必须有终止循环的条件或语句，避免死循环。

（2）       当多层循环嵌套时，计数器变量注意不要有冲突。

（3）       注意循环条件在执行循环过程中是否会发生变化，如果会则必须把循环条件的值在执行循环前获取而不要在每次循环去执行。

（4）       考虑运行效率问题也应把循环条件值放在循环执行前获取。

 

建议：

（1）       使用最基本的for循环，尽量避免使用for …in循环；

（2）       for …in循环可用于用于object/map/hash 的遍历，对 Array 用 for-in 循环有时会出错，不建议使用；

（3）       for循环中条件语句，不应该每次执行一个操作（如计算），应该在初始语句中实现；

// 不建议每次查询length的值 for (var i = 0; i < data.length; i++) {   }

// 建议在初始语句中赋值一个变量 for (var i = 0, len = data.length; i < len; i++) {   }

3.3.3语句规范

原则：

(1)    除了语句块最后一条语句可以没有分号“;”以外，每条语句必须以分号结束，以避免代码压缩后造成解析失败。

(2)    当代码块中只有一条语句，也不应该省略大括号，如

if (null == $tab) { return ; // 虽然只有一条语句，也不应该省略{} }

 

3.3.4运算符规范

原则：

（1）       赋值符号、比较符号两侧的变量应该在同一行，不要进行换行；

（2）       字符串使用单引号（’）要优于双引号（”），尤其是在创建一个包含 HTML 代码的字符串时；

3.4类、对象与原型链规范

原则：

（1）       使用 Array 和 Object 字面量语法, 而不使用 Array 和 Object 构造器（newArray()），避免因传参不合适导致错误；

（2）       其命名规范参考第1节中命名规范；

 

编码风格，建议如下：

1）比较长的标识符或者数值, 不要为了让代码好看些而手工对齐. 如：

CORRECT_Object.prototype = { a: 0, b: 1, lengthyName: 2 };

不要这样做: WRONG_Object.prototype = { a          : 0, b          : 1, lengthyName: 2 };

 

2）属性名与属性值之间不应该拥挤，应该在冒号“:”与属性值之间空一格；

 

3.5错误处理

基本原则：

（1）       通常的法则是系统在正常状态并且用户正常操作下，不应产生任何异常。

（2）       对可预见的错误不进行捕捉。

（3）       对不可预见或者难以解决错误进行try{…}catch(e){..}捕捉处理。

3.5.1可预见错误

对可预见的错误不进行捕捉处理，而是在错误发生前通过条件判断避免发生，如：

//若不对div1是否为null进行检查，则在其为null时会抛出缺少对象错误 document.getElementById(“div1”).style.width = 100;

//预先对对象进行检查 var objDiv1 = document.getElementById(“div1”); if(objDiv1!=null){        objDiv1.style.width = 100; }

3.5.2不可预见错误

对不可预见或者因浏览器、脚本解析器BUG造成的难以解决的错误需要进行捕捉处理，如：

try{        xmlhttp.open(“GET”,url,NOT_ASYNC); }catch(e){        console.log(e.description); }

 

【说明】：对捕捉到的错误一般情况必须给出反馈处理，例如console.log()，除非有必要提醒用户，否则不应该使用alert()。

4 JavaScript其他规范

以下规范，除了说明为建议、格式外，均为必须遵循的原则：

（1）      eval是恶魔。eval 是JavaScript中最容易被滥用的方法，避免使用它。

（2）      不要给setTimeout或者setInterval 传递字符串参数，应该使用函数参数。

（3）      this仅在对象构造器, 方法, 闭包中使用。
this 的语义很特别。 有时它引用一个全局对象(大多数情况下)，调用者的作用域，DOM 树中的节点(添加事件处理函数时)， 新创建的对象(使用一个构造器)，或者其他对象(如果函数被call()或apply())。使用时很容易出错。

【说明】：在内嵌函数想要使用外层函数的调用者，必须将外层调用者赋值给一个变量，通常是self。

（4）      不要使用with(){}。

（5）      千万不要修改内置对象, 如Object.prototype 和 Array.prototype 的原型；

（6）      使用 join() 来创建字符串。

通常是这样使用的，但这样在 IE 下非常慢: function listHtml(items) { var html = '<div class="foo">'; for (var i = 0, len = items.length; i < len; ++i) { if (i > 0) { html += ', '; } html += itemHtml(items[i]); } html += '</div>'; return html; }

可以用下面的方式: function listHtml(items) { var html = []; for (var i = 0, len = items.length; i < len; ++i) { html[i] = itemHtml(items[i]); } return '<div class="foo">' + html.join(', ') + '</div>'; }

【说明】：即用数组作为字符串构造器, 然后通过join('') 转换成字符串。不过由于赋值操作快于数组的 push(), 所以尽量使用赋值操作.

 

 

 

 

 

 

 

 

 

 

 

 

 

【参考文献】

[1] JavaScript编程规范. http://wenku.baidu.com/view/f3a4cde95ef7ba0d4a733b38.html
[2] Google JavaScript 编码规范指南. http://wenku.baidu.com/view/3a045b66b84ae45c3b358c18.html?re=view
[3] js编码规范. http://wenku.baidu.com/view/ccd97ba20029bd64783e2c0e.html
[4] javascript编程规范. http://wenku.baidu.com/view/b6e6a7d376eeaeaad1f3301e.html