前端代码规范 —— JavaScript篇

[Samgao0312]

JavaScript编码规范

• eslint-config-airbnb 翻译版

---

一、 前言

二、 代码风格

　　2.1 文件

　　2.2 结构

　　　　2.2.1 缩进

　　　　2.2.2 空格

　　　　2.2.3 换行

　　　　2.2.4 语句

　　2.3 命名

　　2.4 注释

　　　　2.4.1 单行注释

　　　　2.4.2 多行注释

　　　　2.4.3 文档化注释

　　　　2.4.4 类型定义

　　　　2.4.5 文件注释

　　　　2.4.6 命名空间注释

　　　　2.4.7 类注释

　　　　2.4.8 函数/方法注释

　　　　2.4.9 事件注释

　　　　2.4.10 常量注释

　　　　2.4.11 复杂类型注释

　　　　2.4.12 AMD 模块注释

　　　　2.4.13 细节注释

三、 语言特性

　　3.1 变量

　　3.2 条件

　　3.3 循环

　　3.4 类型

　　　　3.4.1 类型检测

　　　　3.4.2 类型转换

　　3.5 字符串

　　3.6 对象

　　3.7 数组

　　3.8 函数

　　　　3.8.1 函数长度

　　　　3.8.2 参数设计

四、 浏览器环境

　　4.1 DOM

　　　　4.1.1 元素获取

　　　　4.1.2 样式获取

　　　　4.1.3 样式设置

　　　　4.1.4 DOM 操作

　　　　4.1.5 DOM 事件

---

一、 前言

写这个文档的目标是使 JavaScript 代码风格保持一致，容易被理解和被维护。

虽然本文档是针对 JavaScript 设计的，但是在使用各种 JavaScript 的预编译语言(如 TypeScript 等)时，适用的部分也应尽量遵循本文档的约定。

---

二、 代码风格

2.1 文件

[建议] JavaScript 文件使用无 BOM 的 UTF-8 编码。

解释：UTF-8 编码具有 更广泛的适应性。BOM 在使用程序或工具处理文件时可能造成不必要的干扰。

[建议] 在文件结尾处，保留一个空行。

2.2 结构

2.2.1 缩进

[强制] 使用 2 个空格做为一个缩进层级，不允许使用 4 个空格 或 tab 字符。

[强制] switch 下的 case 和 default 必须增加一个缩进层级。

示例：

// good
switch (variable) {

    case '1':
        // do...
        break;

    case '2':
        // do...
        break;

    default:
        // do...

}

// bad
switch (variable) {

case '1':
    // do...
    break;

case '2':
    // do...
    break;

default:
    // do...

}

2.2.2 空格

[强制] 二元运算符两侧必须有一个空格，一元运算符与操作对象之间不允许有空格。

示例：

var a = !arr.length;
a++;
a = b + c;

[强制] 用作代码块起始的左花括号 { 前必须有一个空格。

示例：

// good
if (condition) {
}

while (condition) {
}

function funcName() {
}

// bad
if (condition){
}

while (condition){
}

function funcName(){
}

[强制] if / else / for / while / function / switch / do / try / catch / finally 关键字后，必须有一个空格。

示例：

// good
if (condition) {
}

while (condition) {
}

(function () {
})();

// bad
if(condition) {
}

while(condition) {
}

(function() {
})();

[强制] 在对象创建时，属性中的 : 之后必须有空格，: 之前不允许有空格。

示例：

// good
var obj = {
    a: 1,
    b: 2,
    c: 3
};

// bad
var obj = {
    a : 1,
    b:2,
    c :3
};

[强制] 函数声明、具名函数表达式、函数调用中，函数名和 ( 之间不允许有空格。

示例：

// good
function funcName() {
}

var funcName = function funcName() {
};

funcName();

// bad
function funcName () {
}

var funcName = function funcName () {
};

funcName ();

[强制] , 和 ; 前不允许有空格。如果不位于行尾，, 和 ; 后必须跟一个空格。

示例：

// good
callFunc(a, b);

// bad
callFunc(a , b) ;

[强制] 在函数调用、函数声明、括号表达式、属性访问、if / for / while / switch / catch 等语句中，() 和 [] 内紧贴括号部分不允许有空格。

示例：

// good

callFunc(param1, param2, param3);

save(this.list[this.indexes[i]]);

needIncream && (variable += increament);

if (num > list.length) {
}

while (len--) {
}


// bad

callFunc( param1, param2, param3 );

save( this.list[ this.indexes[ i ] ] );

needIncreament && ( variable += increament );

if ( num > list.length ) {
}

while ( len-- ) {
}

2.2.3 换行

[强制] 每个独立语句结束后必须换行。

[强制] 每行不得超过 120 个字符。

[强制] 在函数声明、函数表达式、函数调用、对象创建、数组创建、for 语句等场景中，不允许在 , 或 ; 前换行。

示例：

// good
var obj = {
    a: 1,
    b: 2,
    c: 3
};

foo(
    aVeryVeryLongArgument,
    anotherVeryLongArgument,
    callback
);


// bad
var obj = {
    a: 1
    , b: 2
    , c: 3
};

foo(
    aVeryVeryLongArgument
    , anotherVeryLongArgument
    , callback
);

[建议] 不同行为或逻辑的语句集，使用空行隔开，更易阅读。

示例：

// 仅为按逻辑换行的示例，不代表setStyle的最优实现
function setStyle(element, property, value) {
    if (element == null) {
        return;
    }

    element.style[property] = value;
}

2.2.4 语句

[强制] 不得省略语句结束的分号。

[强制] 在 if / else / for / do / while 语句中，即使只有一行，也不得省略块 {...}。

示例：

// good
if (condition) {
    callFunc();
}

// bad
if (condition) callFunc();
if (condition)
    callFunc();

[强制] 函数定义结束不允许添加分号。

示例：

// good
function funcName() {
}

// bad
function funcName() {
};

// 如果是函数表达式，分号是不允许省略的。
var funcName = function () {
};

[强制] IIFE 必须在函数表达式外添加 (，非 IIFE 不得在函数表达式外添加 (。

解释：

IIFE = Immediately-Invoked Function Expression.

额外的 ( 能够让代码在阅读的一开始就能判断函数是否立即被调用，进而明白接下来代码的用途。而不是一直拖到底部才恍然大悟。

示例：

// good
var task = (function () { //IIFE
   // Code
   return result;
})();

var func = function () { //非IIFE
};


// bad
var task = function () { // IIFE
    // Code
    return result;
}();

var func = (function () { //非IIFE
});

2.3 命名

[强制] 变量 使用 Camel命名法。

示例：

var loadingModules = {};

[强制] 常量 使用 全部字母大写，单词间下划线分隔 的命名方式。

示例：

var HTML_ENTITY = {};

[强制] 函数 使用 Camel命名法。

示例：

function stringFormat(source) {
}

[强制] 函数的 参数 使用 Camel命名法。

示例：

function hear(theBells) {
}

[强制] 类 使用 Pascal命名法。

示例：

function TextNode(options) {
}

[强制] 类的 方法 / 属性 使用 Camel命名法。

示例：

function TextNode(value, engine) {
    this.value = value;
    this.engine = engine;
}

TextNode.prototype.clone = function () {
    return this;
};

[强制] 枚举变量 使用 Pascal命名法，枚举的属性 使用 全部字母大写，单词间下划线分隔 的命名方式。

示例：

var TargetState = {
    READING: 1,
    READED: 2,
    APPLIED: 3,
    READY: 4
};

[强制] 命名空间 使用 Camel命名法。

示例：

equipments.heavyWeapons = {};

[强制] 由多个单词组成的缩写词，在命名中，根据当前命名法和出现的位置，所有字母的大小写与首字母的大小写保持一致。

示例：

function XMLParser() {
}

function insertHTML(element, html) {
}

var httpRequest = new HTTPRequest();

[强制] 类名 使用 名词。

示例：

function Engine(options) {
}

[建议] 函数名 使用 动宾短语。

示例：

function getStyle(element) {
}

[建议] boolean 类型的变量使用 is 或 has 开头。

示例：

var isReady = false;
var hasMoreCommands = false;

[建议] Promise对象 用 动宾短语的进行时 表达。

示例：

var loadingData = ajax.get('url');
loadingData.then(callback);

2.4 注释

2.4.1 单行注释

[强制] 必须独占一行。// 后跟一个空格，缩进与下一行被注释说明的代码一致。

2.4.2 多行注释

[建议] 使用 /*...*/ 这样的多行注释。或使用多个单行注释。

2.4.3 文档化注释

[强制] 为了便于代码阅读和自文档化，以下内容必须包含以 /**...*/ 形式的块注释中。

解释：

1. 文件
2. namespace
3. 类
4. 函数或方法
5. 类属性
6. 事件
7. 全局变量
8. 常量
9. AMD 模块

[强制] 文档注释前必须空一行。

[建议] 自文档化的文档说明 what，而不是 how。

2.4.4 类型定义

[强制] 类型定义都是以 { 开始, 以 } 结束。

解释：

常用类型如：{string}, {number}, {boolean}, {Object}, {Function}, {RegExp}, {Array}, {Date}。

类型不仅局限于内置的类型，也可以是自定义的类型。比如定义了一个类 Developer，就可以使用它来定义一个参数和返回值的类型。

[强制] 对于基本类型 {string}, {number}, {boolean}，首字母必须小写。

类型定义	语法示例	解释
String	{string}	--
Number	{number}	--
Boolean	{boolean}	--
Object	{Object}	--
Function	{Function}	--
RegExp	{RegExp}	--
Array	{Array}	--
Date	{Date}	--
单一类型集合	{Array.<string>}	string 类型的数组
多类型	{(number｜boolean)}	可能是 number 类型, 也可能是 boolean 类型
允许为null	{?number}	可能是 number, 也可能是 null
不允许为null	{!Object}	Object 类型, 但不是 null
Function类型	{function(number, boolean)}	函数, 形参类型
Function带返回值	{function(number, boolean):string}	函数, 形参, 返回值类型
Promise	Promise.<resolveType, rejectType>	Promise，成功返回的数据类型，失败返回的错误类型
参数可选	@param {string=} name	可选参数, =为类型后缀
可变参数	@param {...number} args	变长参数, ...为类型前缀
任意类型	{*}	任意类型
可选任意类型	@param {*=} name	可选参数，类型不限
可变任意类型	@param {...*} args	变长参数，类型不限

2.4.5 文件注释

[强制] 文件顶部必须包含文件注释，用 @file 标识文件说明。

示例：

/**
 * @file Describe the file
 */

[建议] 文件注释中可以用 @author 标识开发者信息。

解释：
开发者信息 能够体现开发人员对文件的贡献，并且能够让遇到问题或希望了解相关信息的人找到维护人。通常情况文件在被创建时标识的是创建者。随着项目的进展，越来越多的人加入，参与这个文件的开发，新的作者应该被加入 @author 标识。

@author 标识具有多人时，原则是按照 责任 进行排序。通常的说就是如果有问题，就是找第一个人应该比找第二个人有效。比如文件的创建者由于各种原因，模块移交给了其他人或其他团队，后来因为新增需求，其他人在新增代码时，添加 @author 标识应该把自己的名字添加在创建人的前面。

@author 中的名字不允许被删除。任何劳动成果都应该被尊重。

示例：

/**
 * @file Describe the file
 * @author author-name(mail-name@domain.com)
 *         author-name2(mail-name2@domain.com)
 */

2.4.6 命名空间注释

[建议] 命名空间使用 @namespace 标识。

示例：

/**
 * @namespace
 */
var util = {};

2.4.7 类注释

[建议] 使用 @class 标记类或构造函数。

解释：

对于使用对象 constructor 属性来定义的构造函数，可以使用 @constructor 来标记。

示例：

/**
 * 描述
 *
 * @class
 */
function Developer() {
    // constructor body
}

[建议] 使用 @extends 标记类的继承信息。

示例：

/**
 * 描述
 *
 * @class
 * @extends Developer
 */
function Fronteer() {
    Developer.call(this);
    // constructor body
}
util.inherits(Fronteer, Developer);

[强制] 使用包装方式扩展类成员时， 必须通过 @lends 进行重新指向。

解释：

没有 @lends 标记将无法为该类生成包含扩展类成员的文档。

示例：

/**
 * 类描述
 *
 * @class
 * @extends Developer
 */
function Fronteer() {
    Developer.call(this);
    // constructor body
}

util.extend(
    Fronteer.prototype,
    /** @lends Fronteer.prototype */{
        getLevel: function () {
            // TODO
        }
    }
);

[强制] 类的属性或方法等成员信息不是 public 的，应使用 @protected 或 @private 标识可访问性。

解释：

生成的文档中将有可访问性的标记，避免用户直接使用非 public 的属性或方法。

示例：

/**
 * 类描述
 *
 * @class
 * @extends Developer
 */
var Fronteer = function () {
    Developer.call(this);

    /**
     * 属性描述
     *
     * @type {string}
     * @private
     */
    this.level = 'T12';

    // constructor body
};
util.inherits(Fronteer, Developer);

/**
 * 方法描述
 *
 * @private
 * @return {string} 返回值描述
 */
Fronteer.prototype.getLevel = function () {
};

2.4.8 函数/方法注释

[强制] 函数/方法注释必须包含函数说明，有参数和返回值时必须使用注释标识。

解释：

当 return 关键字仅作退出函数/方法使用时，无须对返回值作注释标识。

[强制] 参数和返回值注释必须包含类型信息，且不允许省略参数的说明。

[建议] 当函数是内部函数，外部不可访问时，可以使用 @inner 标识。

示例：

/**
 * 函数描述
 *
 * @param {string} p1 参数1的说明
 * @param {string} p2 参数2的说明，比较长
 *     那就换行了.
 * @param {number=} p3 参数3的说明（可选）
 * @return {Object} 返回值描述
 */
function foo(p1, p2, p3) {
    var p3 = p3 || 10;
    return {
        p1: p1,
        p2: p2,
        p3: p3
    };
}

[强制] 对 Object 中各项的描述， 必须使用 @param 标识。

示例：

/**
 * 函数描述
 *
 * @param {Object} option 参数描述
 * @param {string} option.url option项描述
 * @param {string=} option.method option项描述，可选参数
 */
function foo(option) {
    // TODO
}

[建议] 重写父类方法时， 应当添加 @override 标识。如果重写的形参个数、类型、顺序和返回值类型均未发生变化，可省略 @param、@return，仅用 @override 标识，否则仍应作完整注释。

解释：

简而言之，当子类重写的方法能直接套用父类的方法注释时可省略对参数与返回值的注释。

2.4.9 事件注释

[强制] 必须使用 @event 标识事件，事件参数的标识与方法描述的参数标识相同。

示例：

/**
 * 值变更时触发
 *
 * @event Select#change
 * @param {Object} e e描述
 * @param {string} e.before before描述
 * @param {string} e.after after描述
 */
this.fire(
    'change',
    {
        before: 'foo',
        after: 'bar'
    }
);

[强制] 在会广播事件的函数前使用 @fires 标识广播的事件，在广播事件代码前使用 @event 标识事件。

[建议] 对于事件对象的注释，使用 @param 标识，生成文档时可读性更好。

示例：

/**
 * 点击处理
 *
 * @fires Select#change
 * @private
 */
Select.prototype.clickHandler = function () {

    /**
     * 值变更时触发
     *
     * @event Select#change
     * @param {Object} e e描述
     * @param {string} e.before before描述
     * @param {string} e.after after描述
     */
    this.fire(
        'change',
        {
            before: 'foo',
            after: 'bar'
        }
    );
};

2.4.10 常量注释

[强制] 常量必须使用 @const 标记，并包含说明和类型信息。

示例：

/**
 * 常量说明
 *
 * @const
 * @type {string}
 */
var REQUEST_URL = 'myurl.do';

2.4.11 复杂类型注释

[建议] 对于类型未定义的复杂结构的注释，可以使用 @typedef 标识来定义。

示例：

// `namespaceA~` 可以换成其它 namepaths 前缀，目的是为了生成文档中能显示 `@typedef` 定义的类型和链接。
/**
 * 服务器
 *
 * @typedef {Object} namespaceA~Server
 * @property {string} host 主机
 * @property {number} port 端口
 */

/**
 * 服务器列表
 *
 * @type {Array.<namespaceA~Server>}
 */
var servers = [
    {
        host: '1.2.3.4',
        port: 8080
    },
    {
        host: '1.2.3.5',
        port: 8081
    }
];

2.4.12 细节注释

对于内部实现、不容易理解的逻辑说明、摘要信息等，我们可能需要编写 细节注释。

[建议] 细节注释遵循单行注释的格式。说明必须换行时，每行是一个单行注释的起始。

示例：

function foo(p1, p2, opt_p3) {
    // 这里对具体内部逻辑进行说明
    // 说明太长需要换行
    for (...) {
        ....
    }
}

[强制] 有时我们会使用一些特殊标记进行说明。特殊标记必须使用单行注释的形式。下面列举了一些常用标记：

解释：

1. TODO: 有功能待实现。此时需要对将要实现的功能进行简单说明。
2. FIXME: 该处代码运行没问题，但可能由于时间赶或者其他原因，需要修正。此时需要对如何修正进行简单说明。
3. HACK: 为修正某些问题而写的不太好或者使用了某些诡异手段的代码。此时需要对思路或诡异手段进行描述。
4. XXX: 该处存在陷阱。此时需要对陷阱进行描述。

---

三、 语言特性

3.1 变量

[强制] 变量、函数在使用前必须先定义。

解释：不通过 var 定义变量将导致变量污染全局环境。

示例：

// good
var name = 'MyName';

// bad
name = 'MyName';

原则上不建议使用全局变量，对于已有的全局变量或第三方框架引入的全局变量，需要根据检查工具的语法标识。

示例：

/* globals jQuery */
var element = jQuery('#element-id');

[强制] 每个 var 只能声明一个变量。

解释：一个 var 声明多个变量，容易导致较长的行长度，并且在修改时容易造成逗号和分号的混淆。

示例：

// good
var hangModules = [];
var missModules = [];
var visited = {};

// bad
var hangModules = [],
    missModules = [],
    visited = {};

[强制] 变量必须 即用即声明，不得在函数或其它形式的代码块起始位置统一声明所有变量。

解释：

变量声明与使用的距离越远，出现的跨度越大，代码的阅读与维护成本越高。虽然JavaScript的变量是函数作用域，还是应该根据编程中的意图，缩小变量出现的距离空间。

示例：

// good
function kv2List(source) {
    var list = [];

    for (var key in source) {
        if (source.hasOwnProperty(key)) {
            var item = {
                k: key,
                v: source[key]
            };

            list.push(item);
        }
    }

    return list;
}

// bad
function kv2List(source) {
    var list = [];
    var key;
    var item;

    for (key in source) {
        if (source.hasOwnProperty(key)) {
            item = {
                k: key,
                v: source[key]
            };

            list.push(item);
        }
    }

    return list;
}

3.2 条件

[强制] 在 Equality Expression 中使用类型严格的 ===。仅当判断 null 或 undefined 时，允许使用 == null。

解释：

使用 === 可以避免等于判断中隐式的类型转换。

示例：

// good
if (age === 30) {
    // ......
}

// bad
if (age == 30) {
    // ......
}

[建议] 尽可能使用简洁的表达式。

示例：

// 字符串为空

// good
if (!name) {
    // ......
}

// bad
if (name === '') {
    // ......
}

// 字符串非空

// good
if (name) {
    // ......
}

// bad
if (name !== '') {
    // ......
}

// 数组非空

// good
if (collection.length) {
    // ......
}

// bad
if (collection.length > 0) {
    // ......
}

// 布尔不成立

// good
if (!notTrue) {
    // ......
}

// bad
if (notTrue === false) {
    // ......
}

// null 或 undefined

// good
if (noValue == null) {
  // ......
}

// bad
if (noValue === null || typeof noValue === 'undefined') {
  // ......
}

[建议] 按执行频率排列分支的顺序。

解释：

按执行频率排列分支的顺序好处是：

1. 阅读的人容易找到最常见的情况，增加可读性。
2. 提高执行效率。

[建议] 对于相同变量或表达式的多值条件，用 switch 代替 if。

示例：

// good
switch (typeof variable) {
    case 'object':
        // ......
        break;
    case 'number':
    case 'boolean':
    case 'string':
        // ......
        break;
}

// bad
var type = typeof variable;
if (type === 'object') {
    // ......
}
else if (type === 'number' || type === 'boolean' || type === 'string') {
    // ......
}

3.3 循环

[建议] 不要在循环体中包含函数表达式，事先将函数提取到循环体外。

解释：循环体中的函数表达式，运行过程中会生成循环次数个函数对象。

示例：

// good
function clicker() {
    // ......
}

for (var i = 0, len = elements.length; i < len; i++) {
    var element = elements[i];
    addListener(element, 'click', clicker);
}


// bad
for (var i = 0, len = elements.length; i < len; i++) {
    var element = elements[i];
    addListener(element, 'click', function () {});
}

[建议] 对循环内多次使用的不变值，在循环外用变量缓存。

示例：

// good
var width = wrap.offsetWidth + 'px';
for (var i = 0, len = elements.length; i < len; i++) {
    var element = elements[i];
    element.style.width = width;
    // ......
}


// bad
for (var i = 0, len = elements.length; i < len; i++) {
    var element = elements[i];
    element.style.width = wrap.offsetWidth + 'px';
    // ......
}

3.4 类型

3.4.1 类型检测

[建议] 类型检测优先使用 typeof。对象类型检测使用 instanceof。null 或 undefined 的检测使用 == null。

示例：

// string
typeof variable === 'string'

// number
typeof variable === 'number'

// boolean
typeof variable === 'boolean'

// Function
typeof variable === 'function'

// Object
typeof variable === 'object'

// RegExp
variable instanceof RegExp

// Array
variable instanceof Array

// null
variable === null

// null or undefined
variable == null

// undefined
typeof variable === 'undefined'

3.4.2 类型转换

[建议] 转换成 string 时，使用 + ''。

示例：

// good
num + '';

// bad
new String(num);
num.toString();
String(num);

[建议] 转换成 number 时，通常使用 +。

示例：

// good
+str;

// bad
Number(str);

[建议] string 转换成 number，要转换的字符串结尾包含非数字并期望忽略时，使用 parseInt。

示例：

var width = '200px';
parseInt(width, 10);

[强制] 使用 parseInt 时，必须指定进制。

示例：

// good
parseInt(str, 10);

// bad
parseInt(str);

[建议] 转换成 boolean 时，使用 !!。

示例：

var num = 3.14;
!!num;

[建议] number 去除小数点，使用 Math.floor / Math.round / Math.ceil，不使用 parseInt。

示例：

// good
var num = 3.14;
Math.ceil(num);

// bad
var num = 3.14;
parseInt(num, 10);

3.5 字符串

[强制] 字符串开头和结束使用单引号 '。

解释：

1. 输入单引号不需要按住 shift，方便输入。
2. 实际使用中，字符串经常用来拼接 HTML。为方便 HTML 中包含双引号而不需要转义写法。

示例：

var str = '我是一个字符串';
var html = '<div class="cls">拼接HTML可以省去双引号转义</div>';

[建议] 使用 数组 或 + 拼接字符串。

解释：

1. 使用 + 拼接字符串，如果拼接的全部是 StringLiteral，压缩工具可以对其进行自动合并的优化。所以，静态字符串建议使用 + 拼接。
2. 在现代浏览器下，使用 + 拼接字符串，性能较数组的方式要高。
3. 如需要兼顾老旧浏览器，应尽量使用数组拼接字符串。

示例：

// 使用数组拼接字符串
var str = [
    // 推荐换行开始并缩进开始第一个字符串, 对齐代码, 方便阅读.
    '<ul>',
        '<li>第一项</li>',
        '<li>第二项</li>',
    '</ul>'
].join('');

// 使用 `+` 拼接字符串
var str2 = '' // 建议第一个为空字符串, 第二个换行开始并缩进开始, 对齐代码, 方便阅读
    + '<ul>',
    +    '<li>第一项</li>',
    +    '<li>第二项</li>',
    + '</ul>';

[建议] 使用字符串拼接的方式生成HTML，需要根据语境进行合理的转义。

解释：

在 JavaScript 中拼接，并且最终将输出到页面中的字符串，需要进行合理转义，以防止安全漏洞。下面的示例代码为场景说明，不能直接运行。

示例：

// HTML 转义
var str = '<p>' + htmlEncode(content) + '</p>';

// HTML 转义
var str = '<input type="text" value="' + htmlEncode(value) + '">';

// URL 转义
var str = '<a href="/?key=' + htmlEncode(urlEncode(value)) + '">link</a>';

// JavaScript字符串 转义 + HTML 转义
var str = '<button onclick="check(\'' + htmlEncode(strLiteral(name)) + '\')">提交</button>';

3.6 对象

[强制] 使用对象字面量 {} 创建新 Object。

示例：

// good
var obj = {};

// bad
var obj = new Object();

[建议] 对象创建时，如果一个对象的所有 属性 均可以不添加引号，建议所有 属性 不添加引号。

示例：

var info = {
    name: 'someone',
    age: 28
};

[建议] 对象创建时，如果任何一个 属性 需要添加引号，则所有 属性 建议添加 '。

解释：

如果属性不符合 Identifier 和 NumberLiteral 的形式，就需要以 StringLiteral 的形式提供。

示例：

// good
var info = {
    'name': 'someone',
    'age': 28,
    'more-info': '...'
};

// bad
var info = {
    name: 'someone',
    age: 28,
    'more-info': '...'
};

[强制] 不允许修改和扩展任何原生对象和宿主对象的原型。

示例：

// 以下行为绝对禁止
String.prototype.trim = function () {
};

[建议] 属性访问时，尽量使用 .。

解释：

属性名符合 Identifier 的要求，就可以通过 . 来访问，否则就只能通过 [expr] 方式访问。

通常在 JavaScript 中声明的对象，属性命名是使用 Camel 命名法，用 . 来访问更清晰简洁。部分特殊的属性（比如来自后端的 JSON ），可能采用不寻常的命名方式，可以通过 [expr] 方式访问。

示例：

info.age;
info['more-info'];

[建议] for in 遍历对象时, 使用 hasOwnProperty 过滤掉原型中的属性。

示例：

var newInfo = {};
for (var key in info) {
    if (info.hasOwnProperty(key)) {
        newInfo[key] = info[key];
    }
}

3.7 数组

[强制] 使用数组字面量 [] 创建新数组，除非想要创建的是指定长度的数组。

示例：

// good
var arr = [];

// bad
var arr = new Array();

[强制] 遍历数组不使用 for in。

解释：

数组对象可能存在数字以外的属性, 这种情况下 for in 不会得到正确结果。

示例：

var arr = ['a', 'b', 'c'];

// 这里仅作演示, 实际中应使用 Object 类型
arr.other = 'other things';

// 正确的遍历方式
for (var i = 0, len = arr.length; i < len; i++) {
    console.log(i);
}

// 错误的遍历方式
for (var i in arr) {
    console.log(i);
}

[建议] 不因为性能的原因自己实现数组排序功能，尽量使用数组的 sort 方法。

解释：

自己实现的常规排序算法，在性能上并不优于数组默认的 sort 方法。以下两种场景可以自己实现排序：

1. 需要稳定的排序算法，达到严格一致的排序结果。
2. 数据特点鲜明，适合使用桶排。

[建议] 清空数组使用 .length = 0。

3.8 函数

3.8.1 函数长度

[建议] 一个函数的长度控制在 50 行以内。

解释：

将过多的逻辑单元混在一个大函数中，易导致难以维护。一个清晰易懂的函数应该完成单一的逻辑单元。复杂的操作应进一步抽取，通过函数的调用来体现流程。

特定算法等不可分割的逻辑允许例外。

示例：

function syncViewStateOnUserAction() {
    if (x.checked) {
        y.checked = true;
        z.value = '';
    }
    else {
        y.checked = false;
    }

    if (a.value) {
        warning.innerText = '';
        submitButton.disabled = false;
    }
    else {
        warning.innerText = 'Please enter it';
        submitButton.disabled = true;
    }
}

// 直接阅读该函数会难以明确其主线逻辑，因此下方是一种更合理的表达方式：

function syncViewStateOnUserAction() {
    syncXStateToView();
    checkAAvailability();
}

function syncXStateToView() {
    y.checked = x.checked;

    if (x.checked) {
        z.value = '';
    }
}

function checkAAvailability() {
    if (a.value) {
        clearWarnignForA();
    }
    else {
        displayWarningForAMissing();
    }
}

3.8.2 参数设计

[建议] 一个函数的参数控制在 6 个以内。

解释：

除去不定长参数以外，函数具备不同逻辑意义的参数建议控制在 6 个以内，过多参数会导致维护难度增大。

某些情况下，如使用 AMD Loader 的 require 加载多个模块时，其 callback 可能会存在较多参数，因此对函数参数的个数不做强制限制。

[建议] 通过 options 参数传递非数据输入型参数。

解释：

有些函数的参数并不是作为算法的输入，而是对算法的某些分支条件判断之用，此类参数建议通过一个 options 参数传递。

如下函数：

/**
 * 移除某个元素
 *
 * @param {Node} element 需要移除的元素
 * @param {boolean} removeEventListeners 是否同时将所有注册在元素上的事件移除
 */
function removeElement(element, removeEventListeners) {
    element.parent.removeChild(element);

    if (removeEventListeners) {
        element.clearEventListeners();
    }
}

可以转换为下面的签名：

/**
 * 移除某个元素
 *
 * @param {Node} element 需要移除的元素
 * @param {Object} options 相关的逻辑配置
 * @param {boolean} options.removeEventListeners 是否同时将所有注册在元素上的事件移除
 */
function removeElement(element, options) {
    element.parent.removeChild(element);

    if (options.removeEventListeners) {
        element.clearEventListeners();
    }
}

这种模式有几个显著的优势：

• boolean 型的配置项具备名称，从调用的代码上更易理解其表达的逻辑意义。
• 当配置项有增长时，无需无休止地增加参数个数，不会出现 removeElement(element, true, false, false, 3) 这样难以理解的调用代码。
• 当部分配置参数可选时，多个参数的形式非常难处理重载逻辑，而使用一个 options 对象只需判断属性是否存在，实现得以简化。

---

四、 浏览器环境

4.1 DOM

4.1.1 元素获取

[建议] 对于单个元素，尽可能使用 document.getElementById 获取，避免使用document.all。

[建议] 对于多个元素的集合，尽可能使用 context.getElementsByTagName 获取。其中 context 可以为 document 或其他元素。指定 tagName 参数为 * 可以获得所有子元素。

[建议] 遍历元素集合时，尽量缓存集合长度。如需多次操作同一集合，则应将集合转为数组。

解释：

原生获取元素集合的结果并不直接引用 DOM 元素，而是对索引进行读取，所以 DOM 结构的改变会实时反映到结果中。

示例：

<div></div>
<span></span>

<script>
var elements = document.getElementsByTagName('*');

// 显示为 DIV
alert(elements[0].tagName);

var div = elements[0];
var p = document.createElement('p');
docpment.body.insertBefore(p, div);

// 显示为 P
alert(elements[0].tagName);
</script>

[建议] 获取元素的直接子元素时使用 children。避免使用childNodes，除非预期是需要包含文本、注释和属性类型的节点。

4.1.2 样式获取

[建议] 获取元素实际样式信息时，应使用 getComputedStyle 或 currentStyle。

解释：

通过 style 只能获得内联定义或通过 JavaScript 直接设置的样式。通过 CSS class 设置的元素样式无法直接通过 style 获取。

4.1.3 样式设置

[建议] 尽可能通过为元素添加预定义的 className 来改变元素样式，避免直接操作 style 设置。

[强制] 通过 style 对象设置元素样式时，对于带单位非 0 值的属性，不允许省略单位。

解释：

除了 IE，标准浏览器会忽略不规范的属性值，导致兼容性问题。

4.1.4 DOM 操作

[建议] 操作 DOM 时，尽量减少页面 reflow。

解释：

页面 reflow 是非常耗时的行为，非常容易导致性能瓶颈。下面一些场景会触发浏览器的reflow：

• DOM元素的添加、修改（内容）、删除。
• 应用新的样式或者修改任何影响元素布局的属性。
• Resize浏览器窗口、滚动页面。
• 读取元素的某些属性（offsetLeft、offsetTop、offsetHeight、offsetWidth、scrollTop/Left/Width/Height、clientTop/Left/Width/Height、getComputedStyle()、currentStyle(in IE)) 。

[建议] 尽量减少 DOM 操作。

解释：DOM 操作也是非常耗时的一种操作，减少 DOM 操作有助于提高性能。

4.1.5 DOM 事件

[建议] 优先使用 addEventListener / attachEvent 绑定事件，避免直接在 HTML 属性中或 DOM 的 expando 属性绑定事件处理。

解释：

expando 属性绑定事件容易导致互相覆盖。

[建议] 使用 addEventListener 时第三个参数使用 false。

解释：

标准浏览器中的 addEventListener 可以通过第三个参数指定两种时间触发模型：冒泡和捕获。而 IE 的 attachEvent 仅支持冒泡的事件触发。所以为了保持一致性，通常 addEventListener 的第三个参数都为 false。

[建议] 在没有事件自动管理的框架支持下，应持有监听器函数的引用，在适当时候（元素释放、页面卸载等）移除添加的监听器。