JavaScript编码规范剖析

1、JavaScript编码规范2016 年 02 月 18 H规范基本信息表:规范简称：JavaScript编码规范规范版本号：1.0规范修订日期：2016-02-18本规范位置：先前版本位置：规范制定组织：规范制定牵头人：王军锋规范校订人：第30页JavaScript 编码规范i 概要1.1 规范摘要本规范主要目的是定义基于JavaScript编码的总体规范，确保编码的规范性，提高程序的可维护性。通过遵循共同的编码规范，程序开发人员可以保持代码一贯的风格，提高代码编写的可读性和使用的一贯 性。1.2 背景1.3 现状1.4 相关工作说明1.5 规范声明2适用范围3引言3.1 词汇表3.1.1

2、首选术语3.1.2 相关术语3.2 格式约定3.3 文件引用ECMAScript-262 标准。JavaScript 权威指南V5。JavaScript高级程序设计V2。JavaScript高性能。Google JavaScript开发规范。4需求5规范正文5.1 排版规范5.1.1 文件结构JavaScript文件按如下顺序组织各元素:序号元素说明1版权、版本声明以注释的方式进行声明2总体注释在注释中总体介绍该文件实现的功能； 对如何使用这些功能给出指导性意见； 给出使用示例；指出注意事项；罗列依赖的其它JavaScript文件；注明：第一作者、第二作者 。3程序内容5.1.2 缩进排版以4

3、个空格为一个缩进单元，避免使用Tab制表符。【示例】：function getUser(id) if ( !id ) throw new Error( ” );5.1.3 行排版一行的字符不建议超过120个字符，一行过多的字符会影响查看程序的效率。 如果一段描述不能放在一行中，依据下列规则将其拆分成多行：1) 从分隔符(比如空格)后换行2) 在运算符之前换行；3) 不拆分完整的单词；4) 换行后如果需要缩进则不应缩进超过行中。【示例】：if (conditionl & condition2) | (condition3 & condition4) |!(condition5 & conditi

4、on6) 5.1.4 空白的使用函数之间空1行，get/set方法除外。【示例】：function createUser() function destoryUser() function getUser() return this.user;function setUser(user) this.user = user;代码逻辑段之间空一行。【示例】：function getUser(id) /判断参数id的合法性if ( !id ) throw new Error( ” );/根据参数id查找user对象findUser(id);5.1.5 语句表达式语句表达式语句以分号结束

5、。【示例】：var i = 0;alert(提示信息”)；Math.cos(x);复合语句复合语句是包含在花括号中的一个语句或者语句块，复合语句遵循如下排版规则：1) 左花括号” ”位于复合语句起始行的行尾,右大括号应另起一行并与复合语句首行对齐;2) 花括号中的语句缩进一个层次(4个空格)。返回语句【示例】：var x = 0; if-else 语句if-else语句总是用和括起来，避免发生错误。【示例】：if ( expressionl ) statement else if ( expression2 ) statement2; else statement3

6、; for 语句【示例】：for (initialize; test; increment) statement;一个空的for语句：在初始化，条件判断，更新子句中完成，应该具有如下格式：【示例】：for (initialize; test; increment); for-in 语句【示例】：for ( variable in object ) statement; while 语句【示例】：while ( expression ) statement; do-while 语句【示例】：do statement; while ( exp

7、ression ); switch 语句【示例】：switch ( expression ) case valuel:statement;break;case value2:statement;break;default:statement;break;当一个执行完一个case后需要顺着往下执行(即没有 break语句)时，通常应在break语句的位置添加注释。上面的示例代码中就包含注释 /* */。 try-catch-fi nally语句【示例】：try statement; catch ( e ) statement; finally statement;5.

8、2注释规范5.2.1 注释位置1) 函数和方法：每个函数和方法都应该包含一个注释，描述其目的和用于完成任务所可能使用的算法，基于参数类型、参数可选择值、返回值；2) 大段代码：用于完成单个任务的多行代码应该在前面填加描述任务的注释；3) 复杂的算法：在使用复杂算法的代码处添加注释，以便下次查阅代码时帮助理解；4) Hack:因为不同的浏览器存在差异，JavaScript以便会包含一些hack，需要在这些hack的代码前添加注释，以便提醒代码维护者。5.2.2 块注释块注释以”严”开头或者” ”开头，以”1 ”结尾，Doc注释以” ”开头，比如：注释在 JavaScript文 件开头、函数、变量

9、上的注释通常会用于生成doc文档；非Doc注释的多行注释以 ” ”开头。在Doc注释中需要注明类型，常见的类型包括：Object、Array、Function、Number、String、Boolean、Math等，类型注释规则如下表：符号举例说明类型Object对象类型 | Number | ObjectNumbe或者Object类型 ! !Object非对象类型 ? 未知类型 * 所有类型注：在注释中的Numbe包装类型代指Number类型或者number基本类型，其它包装类型类似。Doc注释举例：【示例】：/* Object用户对象*/var user = ;*通过用户对象获取用户名称*

10、 param Object user 用户对象* return String用户名称*/function getUserName(user) /* 如果user为null，则该方法会出现异常，需要对输入参数user进行可靠性校验* 需判断user变量是否是user对象*/return ;/如果没有返回值，可以不用在注释中写return/*设置用户名称* param Number age 用户名称*/function setUserName(name) = name;5.2.3单行注释单行注释，以” ”开头，非Doc注释时使用。【示例】：function g

11、etUserName(user) /返回用户名称return ;5.2.4 JavaScript 文件注释在文件头位置对JavaScript文件进行注释，说明该文件的版权、版本等信息。【示例】：/* 本文件是$项目名称 V$VERSION勺一部分* Copyright (C) 2000-2011公司名称* Provider:组织名称* 联系方式：*版权说明：*/5.2.5 函数/方法注释【示例】：/*通过用户对象获取用户名称* param Object user 用户对象* return String用户名称*/function getUserName(user) retur

12、n ;5.2.6 变量/属性注释【示例】：* Object 用户对象*/var user = ;5.3 声明规范5.3.1 变量局部变量和全局变量均使用var关键字进行声明。【示例】：var name =;在同一作用域(在JavaScript中共三种作用域：全局作用域、局部作用域、嵌套局部作用域)的开头 位置声明变量，避免出现重复声明变量的问题，for、for-in语句的循环变量除外。【示例】：/全局变量var globaIV =“global ” ;function printUserProperty () /局部变量var users = name:”用户 1 ” , n

13、ame: ”用户 2” ;/for 语句变量i, userfor( var i = 0, user; user = usersi; i+ ) printUserProperty(user);function printUserProperty(user) /嵌套局部变量var count = 10;/for-in 语句变量propfor ( var prop in user ) alert(prop);（通过初值确定变量类型），由于局声明全局变量、对象属性、函数参数时需注释变量类型或者赋初值 部变量是在代码块内部定义，作用范围有限，因此不做要求。【示例】：/全局变量var isSuccess

14、= false;var count = -1;var name =” ;var user = null;/推荐的布尔类型初始值：false /推荐的number类型初始值：-1 /推荐的字符串类型初始值：“”/推荐的对象类型初始值：nullvar obj = /对象属性name =“;/函数参数*设置名称* param string name 名称* return*/function setName(name) 可以一次声明多个变量，变量之间用“，”分隔，如果变量有初值或者注释则需换行，换行后与上一行 的第一个变量左对齐。【示例】：var name, password, age, sex;/有

15、注释或者初值应换行var name, password,age, / 年龄sex = 男；采用直接量的方式声明对象，提高对象声明的代码可读性，对象属性和方法行前空4格,对象的属性或者方法以“，”分隔，最后一个属性或者方法不应出现“，”，属性之间不空行，方法之间空两行。【示例】：/优var user = id:,name ，setName: function(name) = name;,getName: function。return ;/劣var user = new Object();user.id =; =“” ;user.setNa

16、me = function(name) = name;user.getName = function() return ;采用直接量的方式声明数组，尽量不采用构造函数，避免错误。【示例】：/优var arr = x1;/劣/如果x1是正整数，则数组长度 =x1/如果x1是非正整数的number，则会出现error/如果x1是非number类型，数组长度=1,x1将作为数组的一个内容 var arr = new Array(xl);532 函数使用function关键字声明函数。【示例】：function getUser() /函数变量var getUser

17、 = function() 函数参数之间用“，”分隔。【示例】：function createUser(id, name, password) 函数代码行前空4格。【示例】：function getUser() return name:用户” ;相邻函数之间空2行【示例】：function setUser() function setUser(user) 匿名函数的右花括号右端不应有代码，左花括号左端不应有代码。【示例】：excute(whatever, function, p2) )；在script、function的根下声明函数，避免在 if等语句块下声明函数，以符合ECMAScript-

18、262标准。【示例】：/劣：if (x) function foo() /替代方案：使用函数变量if (x) var foo = function() 5.4 命名规范5.4.1 文件当在一个project中引入其它JavaScript文件时，会存在文件名称相同的可能，因此需要采取一定的措 施减少重名的可能性，推荐的方式：公司名称项目名称模块名称 . 子模块名称.js ，文件名称全部小写。【示例】：epri.sotower.ui.grid.js542命名空间在JavaScript中，通过对象的属性模拟命名空间，避免变量、函数重名，推荐的命名规则与文件命名 基本一致。【示例】：/ 在epri.s

19、otower.ui.grid.js文件中为 Grid 对象定义一个方法 createGridvar epri= epri| ;if ( typeof(epri) !=object ) throw new Error( 命名空间epri已经存在但是不是对象！”；epri.sotower = epri.sotower | ;if ( typeof(epri.sotower) !=object ) throw new Error( 命名空间epri.sotower 已经存在但是不是对象！”；epri.sotower.ui = epri.sotower.ui | ;if ( typeof(epri.s

20、otower.ui) !=object ) throw new Error( 命名空间epri.sotower.ui已经存在但是不是对象！”；if (epri.sotower.ui.Grid ) throw new Error( epri.sotower.ui.Grid 已经存在！ ”; sotower.ui.Grid = createGrid: function。;/执行Grid类的createGrid 方法epri.sotower.ui.Grid.createGrid();5.4.3 构造函数/类构造函数是指：初始化一个对象的属性并且专门和new运算符一起使用的函数，通常采用构造函数实现类

21、的概念，构造函数采用首字母大写的驼峰式命名。【示例】：function User(id, name, password) this.id = id; = name;this.password = password;var user = new User( id1 ” 用户” 111111”alert();5.4.4 变量/对象属性在本小节变量代指：变量/对象属性。变量由字母、数字或下划线组成，变量的第一个字符不能是数字，变量的名称不能是JavaScript保留字(参考附录1 )。【示例】：/正确var user = null;var _user = null

22、;var _user1 = null;/错误var 1user = null;var $user = null;变量采用首字母小写的驼峰式命名。【示例】：var userName =”var user = userName: ”；变量名称应具有一定的含义。【示例】：/优var userName =”/劣var aa =;在JavaScript中没有私有变量的语法，但是可以通过注释或者为变量增加”前缀等方式表示为私有变量，通常采用加”前缀的方式。【示例】：var user = /私有变量_roles:.getRoles: function。 return this._roles;5.4.5 常量

23、在JavaScript中没有常量的语法，但是可以采取特殊的命名方式把一个变量表示为常量：所有字母大 写，单词之间用“ _ “链接。【示例】：var MAX_WIDTH = 1024;5.4.6 函数/对象方法对象方法是作为对象属性的函数，因此在本小节中函数代指：函数/对象方法。函数名称由字母、数字或下划线组成，第一个字符不能是数字，函数名称不能是JavaScript保留字(参考附录1)。【示例】：/正确function getUser() function _getUser2() /错误function 1getUser() function get&User() 函数名称采用首字母小写的驼峰

24、式命名。【示例】：function getUser() 函数名称应具有一定的含义。【示例】：/优function getUser() /劣function aa() 函数名称通常以动词开头【示例】：/优function getUser() /劣function user() 变量/对象属性对应的存值、取值方法分别通过set、get命名，如果变量/对象属性是boolean类型，则建议可以使用is替代get，替换后的方法更易理解。【示例】：var user = name:,sex:男，getName: function() return ;,setName: function(n

25、ame) = name;,isBoy: function。return this.sex =男”；5.4.7 事件处理事件的函数名称以“Handler “后缀结尾，在名称中需要包含事件的类型和代表触发事件的HTM元素的名称。【示例】：/在页面中有一个输入用户名称的input框，则处理它的onchange事件的函数命名如下：function userNamelnputChangeHandler(e) 5.5编码健壮性遵循原则5.5.1 合理使用闭包闭包容易导致内存泄露，尤其是使用闭包函数处理DO事件时经常会出现HTM元素与闭包函数的相互引用，从而导致无法释放HTM元素和闭包函

26、数的内存。【示例】：/劣/在执行完foo方法后，局部变量element不会被垃圾回收，因为它的闭包函数被注册到element元素的单击/事件中，被element引用，而闭包函数又持有foo函数内的所有变量包括 element，如此形成element和foo/内的闭包函数的循环引用，从而element和foo均不能被垃圾回收，导致内存泄露。function foo(element, a, b) element.onclick = function() /*使用变量a、b */；/优/改造后的正确用法如下：/ element会引用函数bar返回的函数，不会引用到foo，避免了循环引用，从而执行完f

27、oo方法后，element/将被垃圾回收。function foo(element, a, b) element.onclick = bar(a, b);function bar(a, b) return function() /* 使用 a、b */5.5.2 合理使用for和for-in循环使用普通的for语句循环数组，使用for-in语句循环对象，不建议使用for-in语句循环数组，因为如果使用for-in循环数组在一些使用场景下会导致问题。【示例】：/劣function printArray(arr) for (var key in arr) alert(arrkey);printAr

28、ray(0,1,2,3); /可以 alert 出正确的结果var a = new Array(10);printArray(a); /错误：没有 alerta = document.getElementsByTagName(*);printArray(a); /错误：会 alert 出 a的 length 值错误：会alert 出wine错误：只alert 一次a = 0,1,2,3; a.buhu = wine; printArray(a); /a = new Array; a3 = 3; printArray(a); /优/把以上示例的for-in语句改造成普通的for语句，则不存在以上

29、问题function printArray(arr) var l = arr.length;for (var i = 0; i l; i+) alert(arri);只在循环对象时使用for-i n【示例】：for ( var p in user ) alert(p);/注意添加到对象的prototype中的成员将被包含在遍历中，可以通过使用hasOwnProperty方法来区分是否对象自有属性或者方法。5.5.3避免无限循环1) 在使用for等循环语句进行循环时，要确保终止循环的条件一定能被触发，避免无限循环；2) 避免函数之间相互调用，形成隐式无限循环。【示例】：/错误function f

30、1() f2()；function f2() f1()；f1()；5.5.4 区分=和 =”是完全等于，即除了值必须相等外，类型也必须相等。【示例】：var v1 = 1;var v2 =1 ”；alert(v1 = v2); /truealert( v1 = v2 );/false5.5.5 字符串拼接使用“+”进行字符串多行拼接，不建议使用“”，因为MCMAScript标准不支持“”拼接方式，并且“ ”拼接方式会导致行前的空白被包含在变量中。【示例】：/劣var myString = A rather long string of English text, an error messag

31、e actually that just keeps going and going - an error just gravy. Have a nice day.;/优var myString = A rather long string of English text, an error message + actually that just keeps going and going - an error +just gravy. Have a nice day.;5.5.6 避免在函数中定义全局变量【示例】：/劣function doSomething() user = ; /不使用

32、var关键字会定义一个全局的 user变量5.5.7 避免在JavaScript中包含过多的 HTML CSS内容在JavaScript中尽量少包含 CSS羊式、HTM的内容，如果必须使用 CSS尽量把样式写入 CSS文件，在 JavaScript中对class进行操作，如果必须使用 HTML且HTMI内容比较多，则应该把 HTML关内容归集到一 个文件中，并根据需要使用模板技术。5.5.8 异常处理1) 把可能出现错误的程序块放入try语句中，把处理错误的代码放到catch或者fin ally 语句中；2) ECMAScript只为Error对象定义了两个属性，一个是保存错误信息的messa

33、ge属性，一个是保存错误类型的named性(ECMAScript共定义了 7中错误类型，其中Error是基本错误类型)，但是IE、FireFox等 浏览器通常会为Error添加自有的属性，因此如果应用需要支持跨浏览器，只使用message、name属性。3) 在fin ally子句中使用return语句时，return的应该是一个变量。【示例】：/劣try return 2; catch( e ) finally return 1; /最终返回的永远是1/优var rv = -1;try rv = 2; catch( e ) rv = 1; finally return rv; /如果没有错误

34、则返回2，有错误则返回14) 使用throw关键字抛出异常，throw的应该是Error或者Error的子对象。【示例】：/劣throw “”/优throw new Error(“ msg ); /new 一个 Error 或者 Error 的子对象5) 在可以的情况下，尽量使用throw抛出自己的异常信息，避免出现错误时，显示的是浏览器默认的错误信息，不利于排错，尤其是生产环境下，有较好的自定义错误信息，将对排错提供很好的帮助。【示例】：/优function process(values) if ( !values ) throw new Error( Xx.js参数 values 必须有值

35、”)；6) 只处理可以处理的错误；7) 通过原型prototype继承Error类，实现自定义错误类型。【示例】：function SelfError(message) = SelfError ”；this.message = message;SelfEtotype = new Error();8) 记录JavaScript错误到服务器端，以便分析错误。【示例】：/*通过Image元素记录错误到服务器端* param String level错误级另U, 可选值：debug、info、warn、erorr* param String msg 错误信息*/fu

36、nction logError(level, msg) var img = new Image();img.src =“context/log.so?level=”+ encodeURIComponent(level) +& msg= +encodeURLComponent(msg);for ( var i = 0; i 100; i+ ) try /Code catch ( error ) logError( “info ” ,处理时发生错误，错误时的状态是”);5.6性能优化5.6.1 合理使用 prototype在使用prototype实现继承时，不应层级太多，否则会影响到在子类中使用父

37、类方法时的性能。5.6.2 本地缓存对象属性在多次使用对象属性的程序块中，应该为属性定义本地变量，在后续程序只使用本地变量，这样可以 减少JavaScript引擎在对象中查找属性的次数，提高访问性能，在循环中使用引用时尤其有效。【示例】：var obj = name: ;var name = ;var obj2 = ;for ( var i = 0; i 100; i+ ) = name + i;5.6.3 减少操作HTML DOM结构的次数尽量减少JavaScript操作DOI的次数，在对DO进行新增、替换节点时，可以先把相应的内容准备好后, 通过inne

38、rHTML方式一次完成对DO啲操作。5.6.4 减少在HTML中嵌入过多JavaScript 代码尽量减少在HTM文件中嵌入的JavaScript代码，把JavaScript代码归集到JavaScript文件中，可以借 助JavaScript编译工具进行优化和压缩，从而减小网络流量。565引用 JavaScript 文件vscript src= filename.js ”标签可以放在body的最后，以便减少由于加载script文件而导致其它页面 组件的延迟显示的问题。5.6.6 压缩 JavaScript 文件使用Google Compiler压缩JavaScript文件，在项目中只使用压缩后

39、的JavaScript文件，提高JavaScript文件加载速度。5.6.7 事件代理在为HTM添加较多事件函数时，建议采用事件代理机制，在父节点代理所有子节点进行事件处理，避 免浏览器为子节点注册事件，在子节点比较多时，比如：为表格的每个单元格注册事件处理器时采用机制 代理机制对性能改善尤为明显。6 一致性约束6.1 引言本文档主要是规范实现过程中的编码实现，以保证JavaScript编码的统一，增加可读性、可维护性。6.2 一致性考查表此表用于描述在前述规范中提到的各项规范的约束等级，分为强制和推荐两级。任何强制性约束没有 满足时，处于未遵守此规范的状况；满足所有强制性约束，但未实现部分或

40、全部推荐性约束时，处于遵守 此规范的状况；全部实现所有强制性和推荐性约束时，处于完全符合此规范的状况规范点标记规范点说明约束等级（强制：M，推荐：0）5.1排版规范M5.2注释M5.3声明规范M5.4命名规范M5.5编码健壮性遵循原则M5.6性能优化M5.6.1合理使用prototypeO5.6.2本地缓存对象属性O5.6.3减少操作 HTML DOM 结构的次 数M5.6.4减少在HTML 中嵌入过多JavaScript 代码O5.6.5引用JavaScript文件O5.6.6压缩JavaScript文件M5.6.7事件代理O7附录7.1 保留字正在使用的保留字breakdeletefun ctio nreturntypeofcasedoifswitchvarcatchelseinthisvoidcon ti nuefalsein sta nceofthrowwhiledebuggerfin allynewtruewithdefaultfornulltry为将来保留的字abstractdo