Javascript编码规范

Javascript编码规范 (1.0) o简介▪编撰▪要求o空格o对齐和缩进o换行o行长度▪字符串过长截断▪函数调用时参数过多▪三元运算符过长▪过长的逻辑条件组合▪过长的JSON和数组▪单行和跨行参数混用▪数组和对象初始化的混用o命名▪命名法说明▪变量名▪参数名▪函数名▪方法/属性▪私有（保护）成员▪常量名▪类名▪枚举名▪枚举的属性▪命名空间▪语义o语法▪变量声明▪字符串▪对象、数组和正则▪内置原型▪继承▪异常o注释▪类型定义▪文件注释▪命名空间注释▪类注释▪函数/方法注释▪事件注释▪全局变量注释▪常量注释▪细节注释o其它o参考简介本文档主要的设计目标是商业体系前端Javascript开发风格保持一致，使容易被理解和被维护。

编撰张立理、erik、顾轶灵、李玉北、王海洋、王杨、周莲洁。

本文档由商业运营体系前端技术组审校发布。

要求在本文档中，使用的关键字会以中文+括号包含的关键字英文表示：必须（MUST）。

关键字"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"被定义在rfc2119中。

空格在特定的位置加上空格有助于代码的可读性，以下位置必须（MUST）加上空格：∙除括号外，所有运算符的前后，如∙用作代码块起始的左大括号{前，包括if、else、try、finally这些关键字之后，以及函数定义的参数列表之后∙以下关键字之后：for、switch、while∙对象初始化（{ ... }）的每个属性名的冒号:后∙所有逗号,后∙单行的对象初始化（{ ... }）左大括号{后和右大括号}前注意，在函数参数列表之前不得（MUST NOT）加上空格，以期和函数调用保持一致。

以下是一个函数的正确声明方式：function foo(x, y, z) {// FunctionBody}var foo = function(x, y, z) {// FunctionBody};对齐和缩进必须（MUST）采用4个空格为一次缩进，不得（MUST NOT）采用TAB作为缩进。

在以下情况下必须（MUST）缩进：∙一个代码块与其父代码块相比必须（MUST）多一次缩进∙未结束的语句在换行后必须（MUST）多一次缩进∙switch下的case和default必须（MUST）缩进换行在以下位置必须换行：∙每个独立语句结束后∙if、else、catch、finally、while等关键字前∙运算符处换行时，运算符必须（MUST）在新行的行首对于因为单行长度超过限制时产生的换行，参考行长度中的策略进行分隔。

行长度每一行代码严格以80字符为最大长度，即一行包括前后的空格，不得（MUST NOT）超过80个字符。

由于必定存在一些特殊的原因，导致一条语句的长度超过80，应当（SHOULD）按以下原则进行切分：字符串过长截断按一定长度截断字符串，并使用+运算符进行连接。

分隔字符串尽量按语义进行，如不要在一个完整的名词中间断开。

特别的，对于HTML片段的拼接，通过缩进，保持和HTML相同的结构：var html = '' // 此处用一个空字符串，以便整个HTML片段都在新行严格对齐 + '<article>'+ '<h1>Title here</h1>'+ '<p>This is a paragraph</p>'+ '<footer>Complete</footer>'+ '</article>';也可使用数组来进行拼接，相对+运算更容易调整缩进：var html = ['<article>','<h1>Title here</h1>','<p>This is a paragraph</p>','<footer>Complete</footer>','</article>';];html = html.join(''); // 注意需要join函数调用时参数过多当参数过多，在一行书写函数调用语句会超过80个字符的限制时，应当（SHOULD）将每个参数独立写在一行上，并将结束的右括号)独立一行，所有参数必须（MUST）增加一个缩进，以控制每行的长度，如：// 注意每一个参数的缩进foo(aVeryVeryLongArgument,anotherVeryLongArgument,callback);当参数较多，一行一个书写会导致过长时，应当（SHOULD）按逻辑对参数进行组合，最经典的是baidu.format函数，如：// 将参数分为“模板”和“数据”两块baidu.format(dateFormatTemplate,year, month, date, hour, minute, second);// 将参数分为“模板”、“日期”和“时间”baidu.format(dateFormatTemplate,year, month, date,hour, minute, second);三元运算符过长三元运算符由3部分组成，因此其换行应当（SHOULD）根据每个部分的长度不同，形成3种不同的情况：// 无需换行var result = condition ? resultA : resultB;// 条件超长的情况var result = thisIsAVeryVeryLongCondition? resultA : resultB;// 结果分支超长的情况var result = condition? thisIsAVeryVeryLongResult: resultB;var result = condition? resultA: thisIsAVeryVeryLongResult;不得（MUST NOT）出现以下情况：// 最后一个结果很长，但不建议合并条件和第一分支// 不要这么干var result = condition ? resultA: thisIsAVeryVeryLongResult;这种方法会导致语义上的分裂，即“条件和分支”在一行，“另一分支”在一行，没有按逻辑进行组织。

过长的逻辑条件组合当因为较复杂的逻辑条件组合导致80个字符无法满足需求时，应当（SHOULD）将每个条件独立一行，逻辑运算符放置在行首进行分隔，或将部分逻辑按逻辑组合进行分隔。

最终将右括号)与左大括号{放在独立一行，保证与if内语句块能容易视觉辨识。

如：// 注意逻辑运算符前的缩进if (user.isAuthenticated()&& user.isInRole('admin')&& user.hasAuthority('add-admin')|| user.hasAuthority('delete-admin')) {// Code}过长的JSON和数组如果对象属性较多导致每个属性一行占用空间过大，可以（SHOULD）按语义或逻辑进行分组的组织，如：// 英文-数字的映射var mapping = {one: 1, two: 2, three: 3, four: 4, five: 5,six: 6, seven: 7, eight: 8, nine: 9, ten: 10,eleven: 11, twelve: 12, thirteen: 13, fourteen: 14, fifteen: 15, sixteen: 16, seventeen: 17, eighteen: 18, nineteen: 19, twenty: 20 };通过5个一组的分组，将每一行控制在合理的范围内，并且按逻辑进行了切分。

对于项目较多的数组，也可以（SHOULD）采用相同的方法，如：// 数字-英文的映射var mapping = ['one', 'two', 'three', 'four', 'five','six', 'seven', 'eight', 'nine', 'ten','eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen','sixteen', 'seventeen', 'eighteen', 'nineteen', 'twenty'];单行和跨行参数混用当函数调用时，传递的参数大于或等于2个，且有一个或以上参数跨越多行时，应当（SHOULD）每一个参数独立一行，这通常出现在匿名函数或者对象初始化等作为参数时，如setTimeout函数等：setTimeout(function() {alert('hello');},200);order.data.read('id=' + me.model.id,function(data) {me.attchToModel(data.result);callback();},300);如果认为每个参数单独一行占用过多的空间，则应当（SHOULD）将跨域多行的参数独立出来为一个变量：function attachDataToModel() {me.attchToModel(data.result);callback();}order.data.read('id=' + me.model.id, attachDataToModel, 300);数组和对象初始化的混用必须（MUST）严格按照每个对象的起始{和结束}在独立一行的风格书写，如：var array = [{// ...},{// ...}];命名命名的方法通常有以下几类：命名法说明∙camel命名法，形如thisIsAnApple∙pascal命名法，形如ThisIsAnApple∙下划线命名法，形如this_is_an_apple∙中划线命名法，形如this-is-an-apple根据不同类型的内容，必须（MUST）严格采用如下的命名法：变量名必须（MUST）使用camel命名法参数名必须（MUST）使用camel命名法函数名必须（MUST）使用camel命名法方法/属性必须（MUST）使用camel命名法私有（保护）成员必须（MUST）以下划线_开头常量名必须（MUST）使用全部大写的下划线命名法，如IS_DEBUG_ENABLED类名必须（MUST）使用pascal命名法枚举名必须（MUST）使用pascal命名法枚举的属性必须（MUST）使用全部大写的下划线命名法命名空间必须（MUST）使用camel命名法语义命名同时还需要关注语义，如：∙变量名应当（SHOULD）使用名词∙boolean类型的应当（SHOULD）使用is、has等起头，表示其类型∙函数名应当（SHOULD）用动宾短语∙类名应当（SHOULD）用名词语法变量声明一个var关键字必须（MUST）只声明一个变量。