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

解释：

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

示例：

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

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

示例：

2.4.11 复杂类型注释

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

示例：

2.4.12 AMD 模块注释

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

解释：

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

示例：

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

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

解释：

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

示例：

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

解释：

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

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

示例：

2.4.13 细节注释

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

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

示例：

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

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

解释：

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

3 语言特性

3.1 变量

[强制] 变量在使用前必须通过 var 定义。

解释：

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

示例：

 复制代码
// good
var name = ‘MyName’;
// bad
name = ‘MyName’;

[强制] 每个 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’) {
    // ……
}

[建议] 如果函数或全局中的 else 块后没有任何语句，可以删除 else。

示例：

 复制代码
// good
function getName() {
    if (name) {
        return name;
    }
    return ‘unnamed’;
}
// bad
function getName() {
    if (name) {
        return name;
    }
    else {
        return ‘unnamed’;
    }
}

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’;
    // ……
}

[建议] 对有序集合进行遍历时，缓存 length。

解释：

虽然现代浏览器都对数组长度进行了缓存，但对于一些宿主对象和老旧浏览器的数组对象，在每次 length 访问时会动态计算元素个数，此时缓存 length 能有效提高程序性能。

示例：

 复制代码
for (var i = 0, len = elements.length; i < len; i++) {
    var element = elements[i];
    // ……
}

[建议] 对有序集合进行顺序无关的遍历时，使用逆序遍历。

解释：

逆序遍历可以节省变量，代码比较优化。

示例：

 复制代码
var len = elements.length;
while (len—) {
    var element = elements[len];
    // ……
}

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

[建议] 复杂的数据到视图字符串的转换过程，选用一种模板引擎。

解释：

使用模板引擎有如下好处：

1. 在开发过程中专注于数据，将视图生成的过程由另外一个层级维护，使程序逻辑结构更清晰。
2. 优秀的模板引擎，通过模板编译技术和高质量的编译产物，能获得比手工拼接字符串更高的性能。

• artTemplate: 体积较小，在所有环境下性能高，语法灵活。
• dot.js: 体积小，在现代浏览器下性能高，语法灵活。
• etpl: 体积较小，在所有环境下性能高，模板复用性高，语法灵活。
• handlebars: 体积大，在所有环境下性能高，扩展性高。
• hogon: 体积小，在现代浏览器下性能高。
• nunjucks: 体积较大，性能一般，模板复用性高。

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’];
arr.other = ‘other things’; // 这里仅作演示, 实际中应使用Object类型
// 正确的遍历方式
for (var i = 0, len = arr.length; i < len; i++) {
    console.log(i);
}
// 错误的遍历方式
for (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 = ‘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 参数传递。

如下函数：