JS代码风格指南

一.基本格式

  1. 缩进

    建议每级4个空格，可以给编辑器设置tab = 4个空格，自动转换

  2. 分号

    不要省略分号，防止ASI（自动插入分号）错误

  3. 行宽

    每行代码不超过80个字符，过长应该用操作符手动断行

  4. 断行

    操作符在上一行末尾，且下一行缩进2级，如果是赋值语句，还应该和等号后面部分对齐

  5. 空行

    函数声明与函数声明、变量声明与函数声明、函数内部的逻辑块之间都应该有空行隔开

    作者尼古拉斯还建议在流程控制块顶部留一个空行，但给的例子不是很明确

  6. 命名

    • 变量名/函数名：Camel（驼峰）规则，首词首字母小写，后续词首字母大写，其余部分小写

    • 常量名：C语言式，全大写，下划线分词

    • 构造函数：Pascal规则，所有词首字母大写，其余部分小写

  7. 字面量

    • 字符串：双引号包裹，断行用[+]操作符，不要用\转义字符

    • 数值：不要省略小数点前后的部分，不要用八进制形式

    • Null：只把null当作Object的占位符，不要用来检测形参，也不要用来检测未初始化的变量

    • Undefined：应该把所有对象都初始化为null，以区分未定义和未初始化

    • 对象字面量/数组字面量：不要用构造函数方式声明对象和数组

二.注释

P.S.书中有一句非常经典的解释：

Appropriately written comments help tell the story of code, allowing other developers to drop into a part of the story without needing to hear the beginning.

  1. 单行注释

    • 行尾：用1级缩进隔开代码，而且//后面要有一个空格

    • 独占一行：用来注释下面，要与被注释的代码保持相同的缩进

    • 行首：用来注释多行代码

  2. 多行注释

    用来包裹大段注释，推荐Eclipse风格，例如

    code

/* 
 * comment line1
 * comment line2
 */

    注意：

    • 多行注释上方留一个空行

    • *星号后面留一个空格

    • 多行注释至少三行（因为第一行和最后一行后面不加注释）

  3. 在哪里添注释

    • 不能自解释的代码

    • 故意的，但看起来像是有错的地方

    • 针对浏览器的hack

  4. 文档注释

    应该给各个函数添注释，包括功能描述、参数、返回值、抛出的错误等等，例如推荐的Eclipse风格：

    /**
 * 添加指定元素到默认数组
 * 
 * @method add
 * @param {Number} 将要添加的元素
 * @return {Boolean} 添加成功/失败
 * @throw {TypeError} 参数类型不匹配
 */
function add(item){
    if(typeof item === "number"){
        arr.push(item)
    }
    else{
        throw new TypeError();
    }
}

三.语句和表达式

  1. 花括号对齐方式

    建议行尾风格，不推荐次行风格

  2. 块语句空格

    if后的圆括号部分前后各有一个空格，例如：

    if (expr) {
    code
}

  3. switch语句

    • 缩进：case与switch对齐，break缩进1级

    • case贯穿：用空行或注释//falls through表明case贯穿是故意的

    • default：保留default或者用注释//no default表明没有default

    P.S.《JavaScript语言精粹》的作者道格拉斯认为不应该用case贯穿（称之为鸡肋），因为极易引发bug，而尼古拉斯认为用空行或者注释说明就好了

  4. with语句

    不用

  5. for循环

    所有变量都应该在函数体顶部声明，包括for循环初始化部分用到的变量，避免hosting（提升）引发bug（可能会屏蔽全局变量）

  6. for-in循环

    不要用来遍历数组，用的时候记得加上hasOwnProperty过滤，如果故意遍历原型属性，应该用注释说明

四.变量、函数、操作符

  1. 变量声明

    函数体 = 变量声明 + 函数声明 + 逻辑语句。用空行隔开各个部分

  2. 函数声明

    先声明再使用，千万不要把函数声明放在if分支里，因为浏览器理解不同，而且ES没给标准

  3. 函数调用

    圆括号前后都不加空格，避免和块语句混淆

  4. 匿名函数立即执行

    把立即执行的匿名函数用圆括号包裹，避免与匿名函数声明混淆

  5. 严格模式

    不要在全局作用域开严格模式，只在函数内部开，给多个函数开可以用匿名函数立即执行限定严格模式的作用域

  6. 判断等于

    只用===和!==

  7. eval

    不用eval()和new Function()，用匿名函数优化setTimeout()和setInterval()

  8. 基本包装类型

    不要用new Boolean(), new String(), new Number()

五.风格良好的范例代码

var obj = { // 注意对象字面量的缩进对齐方式

    attr1: 1,  // 注意冒号前后的空格以及本行前的空行
    attr2: (function() {

        // 注意IIFE特别的圆括号位置，不是(function(){})()
    }()),
    _privateAttr: 2,   // 私有属性名以下划线开头

    doSomething: function(arg) {   // 方法名动词开头，而且不用下划线

        // 注意if-else if-else的空格使用以及换行方式
        if (arg === 1) {

        } else if (arg === 2) {

        } else {

        }
    }
}

function Fun() {    // 构造函数名以非动词开始，Pascal规则（注意本行的2个空格）

    // 多个变量应该一起声明，注意等号对齐（注释前面留一行空行）
    var count   = 10,       // 变量名以名词开头，避免与fun混淆，而且不用下划线
        isTrue  = (2 > 1),  // 右边有比较运算时要给右边整体加括号
        color   = 0xcccccc; // 可以用10进制和16进制，不要用8进制，例如011

    /**
     * 注释方法应该用这种文档注释形式，用@param等等
     * 多行注释要保证每行前面有*，并小心对齐
     * 所有的注释（除了行尾单行注释）前面都应该空一行
     */
    function fun(arg1, arg2) {  // 注意本行的3个空格（函数声明与变量声明间隔一行空行）

        var arr = [1, 2, 3],    // 有默认值的属性先声明
            i,                  // 循环（包括for-in）中初始化部分用到的变量也要提前声明
            len;                // 没有默认值的属性后声明

        for (i = 0, len = arr.length; i < len; i++) {

            // 注意for结构中空格的使用
        }

        for (i in arr) {

            // TODO: 注解，表示未完成的任务
            // HACK: 注解，表示针对特定浏览器的hack
            // XXX: 注解，表示很要紧的错误
            // FIXME: 注解，表示不太要紧的错误
            // REVIEW: 注解，表示可能存在更好的实现方式
        }

        while (i < len) {

            switch (i) {

                case 1:
                    /* falls through */

                case 2:
                    break;

                default:
                    break;

                // 或者
                // no default

            }
        }

        do {

            // 所有语句块前都要空一行，注释代码块要用//不要用/**/，后者用来表示注释块
//            try {
//                //
//            } catch (err) {
//                //
//            } finally {
//               //
//            }
        } while (i < len);  // 注意while前后的空格

        return (len > 1 ? true : false);    // 返回值是复杂表达式时要给整体加括号
    }
}

参考资料

  • 《Maintainable JavaScript》

  • 《JavaScript语言精粹》

发表评论

电子邮件地址不会被公开。 必填项已用*标注

*

code