2.2.1. 缩进

·[强制] [RULE003] 使用 4 个空格做为一个缩进层级，不允许使用 2 个空格 或 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. 空格

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

示例

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

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

示例

// good
if (condition) {
}

while (condition) {
}

function funcName() {
}

// bad
if (condition){
}

while (condition){
}

function funcName(){
}

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

示例

// good
if (condition) {
}

while (condition) {
}

(function () {
})();

// bad
if(condition) {
}

while(condition) {
}

(function() {
})();

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

示例

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

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

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

示例

// 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-- ) {
}

·[强制] [RULE012] 单行声明的数组与对象，如果包含元素，{} 和 [] 内紧贴括号部分不允许包含空格。

解释

声明包含元素的数组与对象，只有当内部元素的形式较为简单时，才允许写在一行。元素复杂的情况，还是应该换行书写。

示例

// good
var arr1 = [];
var arr2 = [1, 2, 3];
var obj1 = {};
var obj2 = {name: ‘obj‘};
var obj3 = {
    name: ‘obj‘,
    age: 20,
    sex: 1
};

// bad
var arr1 = [ ];
var arr2 = [ 1, 2, 3 ];
var obj1 = { };
var obj2 = { name: ‘obj‘ };
var obj3 = {name: ‘obj‘, age: 20, sex: 1};

·[强制] [RULE013] 行尾不得有多余的空格。

2.2.3. 换行

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

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

解释

超长的不可分割的代码允许例外，比如复杂的正则表达式。长字符串不在例外之列。

·[强制] 运算符处换行时，运算符必须在新行的行首。

示例

// good
if (user.isAuthenticated()
    && user.isInRole(‘admin‘)
    && user.hasAuthority(‘add-admin‘)
    || user.hasAuthority(‘delete-admin‘)
) {
    // Code
}

var result = number1 + number2 + number3
    + number4 + number5;


// bad
if (user.isAuthenticated() &&
    user.isInRole(‘admin‘) &&
    user.hasAuthority(‘add-admin‘) ||
    user.hasAuthority(‘delete-admin‘)) {
    // Code
}

var result = number1 + number2 + number3 +
    number4 + number5;

·[强制] [RULE017] 在函数声明、函数表达式、函数调用、对象创建、数组创建、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;
}

·[建议] 在语句的行长度超过 120 时，根据逻辑条件合理缩进。

示例

// 较复杂的逻辑条件组合，将每个条件独立一行，逻辑运算符放置在行首进行分隔，或将部分逻辑按逻辑组合进行分隔。
// 建议最终将右括号 ) 与左大括号 { 放在独立一行，保证与 if 内语句块能容易视觉辨识。
if (user.isAuthenticated()
    && user.isInRole(‘admin‘)
    && user.hasAuthority(‘add-admin‘)
    || user.hasAuthority(‘delete-admin‘)
) {
    // Code
}

// 按一定长度截断字符串，并使用 + 运算符进行连接。
// 分隔字符串尽量按语义进行，如不要在一个完整的名词中间断开。
// 特别的，对于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(‘‘);

// 当参数过多时，将每个参数独立写在一行上，并将结束的右括号 ) 独立一行。
// 所有参数必须增加一个缩进。
foo(
    aVeryVeryLongArgument,
    anotherVeryLongArgument,
    callback
);

// 也可以按逻辑对参数进行组合。
// 最经典的是baidu.format函数，调用时将参数分为“模板”和“数据”两块
baidu.format(
    dateFormatTemplate,
    year, month, date, hour, minute, second
);

// 当函数调用时，如果有一个或以上参数跨越多行，应当每一个参数独立一行。
// 这通常出现在匿名函数或者对象初始化等作为参数时，如setTimeout函数等。
setTimeout(
    function () {
        alert(‘hello‘);
    },
    200
);

order.data.read(
    ‘id=‘ + me.model.id,
    function (data) {
        me.attchToModel(data.result);
        callback();
    },
    300
);

// 链式调用较长时采用缩进进行调整。
$(‘#items‘)
    .find(‘.selected‘)
    .highlight()
    .end();

// 三元运算符由3部分组成，因此其换行应当根据每个部分的长度不同，形成不同的情况。
var result = thisIsAVeryVeryLongCondition
    ? resultA : resultB;

var result = condition
    ? thisIsAVeryVeryLongResult
    : resultB;

// 数组和对象初始化的混用，严格按照每个对象的 { 和结束 } 在独立一行的风格书写。
var array = [
    {
        // ...
    },
    {
        // ...
    }
];

·[建议] 对于 if...else... 、 try...catch...finally 等语句，推荐使用在 } 号后添加一个换行 的风格，使代码层次结构更清晰，阅读性更好。

示例

if (condition) {
    // some statements;
}
else {
    // some statements;
}

try {
    // some statements;
}
catch (ex) {
    // some statements;
}

2.2.4. 语句

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

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

示例

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

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

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

示例

// good
function funcName() {
}

// bad
function funcName() {
};

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

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

解释

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

示例

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

var func = function () {
};


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

var func = (function () {
});

2.4.1. 单行注释

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

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}	函数, 形参, 返回值类型
参数可选	@param {string=} name	可选参数, =为类型后缀
可变参数	@param {...number} args	变长参数, ...为类型前缀
任意类型	{*}	任意类型
可选任意类型	@param {*=} name	可选参数，类型不限
可变任意类型	@param {...*} args	变长参数，类型不限

 

2.4.5. 文件注释

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

示例

/**
 * @file Describe the file
 */

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

解释

开发者信息能够体现开发人员对文件的贡献，并且能够让遇到问题或希望了解相关信息的人找到维护人。通常情况文件在被创建时标识的是创建者。

随着项目的进展，越来越多的人加入，参与这个文件的开发，新的作者应该被加入 @author 标识。

@author 标识具有多人时，原则是按照 责任 进行排序。通常的说就是如果有问题，就是找第一个人应该比找第二个人有效。

比如文件的创建者由于各种原因，模块移交给了其他人或其他团队，后来因为新增需求，其他人在新增代码时，添加 @author 标识应该把自己的名字添加在创建人的前面。

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

业务项目中，一个文件可能被多人频繁修改，并且每个人的维护时间都可能不会很长，不建议为文件增加 @author 标识。通过版本控制系统追踪变更，按业务逻辑单元确定模块的维护责任人，通过文档与wiki跟踪和查询，是更好的责任管理方式。

对于业务逻辑无关的技术型基础项目，特别是开源的公共项目，应使用 @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. 函数/方法注释

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

·[强制] 参数和返回值注释必须包含类型信息和说明。

·[建议] 当函数是内部函数，外部不可访问时，可以使用 @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
 * @param {Object} e e描述
 * @param {string} e.before before描述
 * @param {string} e.after after描述
 */
onchange: function (e) {
}

·[强制] 在会广播事件的函数前使用 @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. AMD 模块注释

·[强制] AMD 模块使用 @module 或 @exports 标识。

解释

@exports 与 @module 都可以用来标识模块，区别在于 @module 可以省略模块名称。而只使用 @exports 时在 namepaths 中可以省略 module: 前缀。

示例

define(
    function (require) {

        /**
 * foo description
 *
 * @exports Foo
 */
        var foo = {
            // TODO
        };

        /**
 * baz description
 *
 * @return {boolean} return description
 */
        foo.baz = function () {
            // TODO
        };

        return foo;

    }
);

也可以在 exports 变量前使用 @module 标识：

define(
    function (require) {

        /**
 * module description.
 *
 * @module foo
 */
        var exports = {};


        /**
 * bar description
 *
 */
        exports.bar = function () {
            // TODO
        };

        return exports;
    }
);

如果直接使用 factory 的 exports 参数，还可以：

/**
 * module description.
 *
 * @module
 */
define(
    function (require, exports) {

        /**
 * bar description
 *
 */
        exports.bar = function () {
            // TODO
        };
        return exports;
    }
);

·[强制] 对于已使用 @module 标识为 AMD模块 的引用，在 namepaths 中必须增加 module: 作前缀。

解释

namepaths 没有 module: 前缀时，生成的文档中将无法正确生成链接。

示例

/**
 * 点击处理
 *
 * @fires module:Select#change
 * @private
 */
Select.prototype.clickHandler = function () {
    /**
 * 值变更时触发
 *
 * @event module:Select#change
 * @param {Object} e e描述
 * @param {string} e.before before描述
 * @param {string} e.after after描述
 */
    this.fire(
        ‘change‘,
        {
            before: ‘foo‘,
            after: ‘bar‘
        }
    );
};

·[建议] 对于类定义的模块，可以使用 @alias 标识构建函数。

示例

/**
 * A module representing a jacket.
 * @module jacket
 */
define(
    function () {

        /**
 * @class
 * @alias module:jacket
 */
        var Jacket = function () {
        };

        return Jacket;
    }
);

·[建议] 多模块定义时，可以使用 @exports 标识各个模块。

示例

// one module
define(‘html/utils‘,
    /**
 * Utility functions to ease working with DOM elements.
 * @exports html/utils
 */
    function () {
        var exports = {
        };

        return exports;
    }
);

// another module
define(‘tag‘,
    /** @exports tag */
    function () {
        var exports = {
        };

        return exports;
    }
);

·[建议] 对于 exports 为 Object 的模块，可以使用 @namespace 标识。

解释

使用 @namespace 而不是 @module 或 @exports 时，对模块的引用可以省略 module: 前缀。

·[建议] 对于 exports 为类名的模块，使用 @class 和 @exports 标识。

示例

// 只使用 @class Bar 时，类方法和属性都必须增加 @name Bar#methodName 来标识，与 @exports 配合可以免除这一麻烦，并且在引用时可以省去 module: 前缀。
// 另外需要注意类名需要使用 var 定义的方式。

/**
 * Bar description
 *
 * @see foo
 * @exports Bar
 * @class
 */
var Bar = function () {
    // TODO
};

/**
 * baz description
 *
 * @return {(string|Array)} return description
 */
Bar.prototype.baz = function () {
    // TODO
};

2.4.13. 细节注释

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

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

示例

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

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

解释

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

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);

·[强制] [RULE086] 使用 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.8.1. 函数长度

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

解释

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

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

示例

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

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

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

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

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

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

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 对象只需判断属性是否存在，实现得以简化。

3.8.3. 闭包

·[建议] 在适当的时候将闭包内大对象置为 null 。

解释

在 JavaScript 中，无需特别的关键词就可以使用闭包，一个函数可以任意访问在其定义的作用域外的变量。

需要注意的是，函数的作用域是静态的，即在定义时决定，与调用的时机和方式没有任何关系。

闭包会阻止一些变量的垃圾回收，对于较老旧的JavaScript引擎，可能导致外部所有变量均无法回收。

首先一个较为明确的结论是，以下内容会影响到闭包内变量的回收：

• 嵌套的函数中是否有使用该变量。
• 嵌套的函数中是否有直接调用eval 。
• 是否使用了 with 表达式。

Chakra、V8 和 SpiderMonkey 将受以上因素的影响，表现出不尽相同又较为相似的回收策略，

而JScript.dll和Carakan则完全没有这方面的优化，会完整保留整个 LexicalEnvironment 中的所有变量绑定，造成一定的内存消耗。

由于对闭包内变量有回收优化策略的 Chakra、V8 和 SpiderMonkey 引擎的行为较为相似，因此可以总结如下，当返回一个函数 fn 时：

• 如果 fn 的 [[Scope]] 是ObjectEnvironment（with 表达式生成 ObjectEnvironment，函数和 catch 表达式生成 DeclarativeEnvironment），则：
  1. 如果是 V8 引擎，则退出全过程。
  2. 如果是 SpiderMonkey，则处理该 ObjectEnvironment 的外层 LexicalEnvironment。
• 获取当前 LexicalEnvironment 下的所有类型为 Function 的对象，对于每一个 Function 对象，分析其 FunctionBody：
  1. 如果 FunctionBody 中含有直接调用eval ，则退出全过程。
  2. 否则得到所有的 Identifier。
  3. 对于每一个 Identifier，设其为 name，根据查找变量引用的规则，从 LexicalEnvironment 中找出名称为 name 的绑定 binding。
  4. 对 binding 添加 notSwap 属性，其值为 true。
• 检查当前 LexicalEnvironment 中的每一个变量绑定，如果该绑定有 notSwap 属性且值为 true，则：
  1. 如果是V8引擎，删除该绑定。
  2. 如果是SpiderMonkey，将该绑定的值设为 undefined，将删除 notSwap 属性。

对于Chakra引擎，暂无法得知是按 V8 的模式还是按 SpiderMonkey 的模式进行。

如果有 非常庞大 的对象，且预计会在老旧的引擎 中执行，则使用闭包时，注意将闭包不需要的对象置为空引用。

·[建议] 使用 IIFE 避免 Lift 效应 。

解释

在引用函数外部变量时，函数执行时外部变量的值由运行时决定而非定义时，最典型的场景如下：

var tasks = [];
for (var i = 0; i < 5; i++) {
    tasks[tasks.length] = function () {
        console.log(‘Current cursor is at ‘ + i);
    };
}

var len = tasks.length;
while (len--) {
    tasks[len]();
}

以上代码对 tasks 中的函数的执行均会输出 Current cursor is at 5，往往不符合预期。

此现象称为Lift 效应 。解决的方式是通过额外加上一层闭包函数，将需要的外部变量作为参数传递来解除变量的绑定关系：

var tasks = [];
for (var i = 0; i < 5; i++) {
    // 注意有一层额外的闭包
    tasks[tasks.length] = (function (i) {
        return function () {
            console.log(‘Current cursor is at ‘ + i);
        };
    })(i);
}

var len = tasks.length;
while (len--) {
    tasks[len]();
}

3.8.4. 空函数

·[建议] 空函数不使用 new Function() 的形式。

示例

var emptyFunction = function () {};

·[建议] 对于性能有高要求的场合，建议存在一个空函数的常量，供多处使用共享。

示例

var EMPTY_FUNCTION = function () {};

function MyClass() {
}

MyClass.prototype.abstractMethod = EMPTY_FUNCTION;
MyClass.prototype.hooks.before = EMPTY_FUNCTION;
MyClass.prototype.hooks.after = EMPTY_FUNCTION;

3.9. 面向对象

·[强制] 类的继承方案，实现时需要修正 constructor。

解释

通常使用其他 library 的类继承方案都会进行 constructor 修正。如果是自己实现的类继承方案，需要进行 constructor 修正。

示例

/**
 * 构建类之间的继承关系
 *
 * @param {Function} subClass 子类函数
 * @param {Function} superClass 父类函数
 */
function inherits(subClass, superClass) {
    var F = new Function();
    F.prototype = superClass.prototype;
    subClass.prototype = new F();
    subClass.prototype.constructor = subClass;
}

·[建议] 声明类时，保证 constructor 的正确性。

示例

function Animal(name) {
    this.name = name;
}

// 直接prototype等于对象时，需要修正constructor
Animal.prototype = {
    constructor: Animal,

    jump: function () {
        alert(‘animal ‘ + this.name + ‘ jump‘);
    }
};

// 这种方式扩展prototype则无需理会constructor
Animal.prototype.jump = function () {
    alert(‘animal ‘ + this.name + ‘ jump‘);
};

·[建议] 属性在构造函数中声明，方法在原型中声明。

解释

原型对象的成员被所有实例共享，能节约内存占用。所以编码时我们应该遵守这样的原则：原型对象包含程序不会修改的成员，如方法函数或配置项。

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

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

·[强制] 自定义事件的 事件名 必须全小写。

解释

在 JavaScript 广泛应用的浏览器环境，绝大多数 DOM 事件名称都是全小写的。为了遵循大多数 JavaScript 开发者的习惯，在设计自定义事件时，事件名也应该全小写。

·[强制] 自定义事件只能有一个 event 参数。如果事件需要传递较多信息，应仔细设计事件对象。

解释

一个事件对象的好处有：

• 顺序无关，避免事件监听者需要记忆参数顺序。
• 每个事件信息都可以根据需要提供或者不提供，更自由。
• 扩展方便，未来添加事件信息时，无需考虑会破坏监听器参数形式而无法向后兼容。

·[建议] 设计自定义事件时，应考虑禁止默认行为。

解释

常见禁止默认行为的方式有两种：

• 事件监听函数中 return false。
• 事件对象中包含禁止默认行为的方法，如 preventDefault。

3.10. 动态特性

3.10.1. eval

·[强制] 避免使用直接 eval 函数。

解释

直接 eval，指的是以函数方式调用 eval 的调用方法。直接 eval 调用执行代码的作用域为本地作用域，应当避免。

如果有特殊情况需要使用直接 eval ，需在代码中用详细的注释说明为何必须使用直接 eval ，

不能使用其它动态执行代码的方式，同时需要其他资深工程师进行 Code Review。

·[建议] 尽量避免使用 eval 函数。

3.10.2. 动态执行代码

·[建议] 使用 new Function 执行动态代码。

解释

通过 new Function 生成的函数作用域是全局使用域，不会影响当当前的本地作用域。如果有动态代码执行的需求，建议使用 newFunction 。

示例

var handler = new Function(‘x‘, ‘y‘, ‘return x + y;‘);
var result = handler($(‘#x‘).val(), $(‘#y‘).val());

3.10.3. with

·[建议] 尽量不要使用 with。

解释

使用 with 可能会增加代码的复杂度，不利于阅读和管理；也会对性能有影响。大多数使用 with 的场景都能使用其他方式较好的替代。所以，尽量不要使用 with。

3.10.4. delete

·[建议] 减少 delete 的使用。

解释

如果没有特别的需求，减少或避免使用 delete 。delete 的使用会破坏部分 JavaScript 引擎的性能优化。

·[建议] 处理 delete 可能产生的异常。

解释

对于有被遍历需求，且值 null 被认为具有业务逻辑意义的值的对象，移除某个属性必须使用 delete 操作。

在严格模式或IE下使用 delete 时，不能被删除的属性会抛出异常，因此在不确定属性是否可以删除的情况下，建议添加 try-catch 块。

示例

try {
    delete o.x;
}
catch (deleteError) {
    o.x = null;
}

3.10.5. 对象属性

·[建议] 避免修改外部传入的对象。

解释

JavaScript 因其脚本语言的动态特性，当一个对象未被 seal 或 freeze 时，可以任意添加、删除、修改属性值。

但是随意地对 非自身控制的对象 进行修改，很容易造成代码在不可预知的情况下出现问题。因此，设计良好的组件、函数应该避免对外部传入的对象的修改。

下面代码的 selectNode 方法修改了由外部传入的 datasource 对象。如果 datasource 用在其它场合（如另一个 Tree 实例）下，会造成状态的混乱。

function Tree(datasource) {
    this.datasource = datasource;
}

Tree.prototype.selectNode = function (id) {
    // 从datasource中找出节点对象
    var node = this.findNode(id);
    if (node) {
        node.selected = true;
        this.flushView();
    }
};

对于此类场景，需要使用额外的对象来维护，使用由自身控制，不与外部产生任何交互的 selectedNodeIndex 对象来维护节点的选中状态，不对 datasource 作任何修改。

function Tree(datasource) {
    this.datasource = datasource;
    this.selectedNodeIndex = {};
}

Tree.prototype.selectNode = function (id) {
    // 从datasource中找出节点对象
    var node = this.findNode(id);
    if (node) {
        this.selectedNodeIndex[id] = true;
        this.flushView();
    }
};

除此之外，也可以通过 deepClone 等手段将自身维护的对象与外部传入的分离，保证不会相互影响。

·[建议] 具备强类型的设计。

解释

• 如果一个属性被设计为 boolean 类型，则不要使用 1 / 0 作为其值。对于标识性的属性，如对代码体积有严格要求，可以从一开始就设计为 number 类型且将 0 作为否定值。
• 从 DOM 中取出的值通常为 string 类型，如果有对象或函数的接收类型为 number 类型，提前作好转换，而不是期望对象、函数可以处理多类型的值。

4. 浏览器环境