JS代码风格指南
一.基本格式
-
缩进
建议每级4个空格,可以给编辑器设置tab = 4个空格,自动转换
-
分号
不要省略分号,防止ASI(自动插入分号)错误
-
行宽
每行代码不超过80个字符,过长应该用操作符手动断行
-
断行
操作符在上一行末尾,且下一行缩进2级,如果是赋值语句,还应该和等号后面部分对齐
-
空行
函数声明与函数声明、变量声明与函数声明、函数内部的逻辑块之间都应该有空行隔开
作者尼古拉斯还建议在流程控制块顶部留一个空行,但给的例子不是很明确
-
命名
-
变量名/函数名:Camel(驼峰)规则,首词首字母小写,后续词首字母大写,其余部分小写
-
常量名:C语言式,全大写,下划线分词
-
构造函数:Pascal规则,所有词首字母大写,其余部分小写
-
-
字面量
-
字符串:双引号包裹,断行用[+]操作符,不要用\转义字符
-
数值:不要省略小数点前后的部分,不要用八进制形式
-
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级缩进隔开代码,而且//后面要有一个空格
-
独占一行:用来注释下面,要与被注释的代码保持相同的缩进
-
行首:用来注释多行代码
-
-
多行注释
用来包裹大段注释,推荐Eclipse风格,例如
code /* * comment line1 * comment line2 */
注意:
-
多行注释上方留一个空行
-
*星号后面留一个空格
-
多行注释至少三行(因为第一行和最后一行后面不加注释)
-
-
在哪里添注释
-
不能自解释的代码
-
故意的,但看起来像是有错的地方
-
针对浏览器的hack
-
-
文档注释
应该给各个函数添注释,包括功能描述、参数、返回值、抛出的错误等等,例如推荐的Eclipse风格:
/** * 添加指定元素到默认数组 * * @method add * @param {Number} 将要添加的元素 * @return {Boolean} 添加成功/失败 * @throw {TypeError} 参数类型不匹配 */ function add(item){ if(typeof item === "number"){ arr.push(item) } else{ throw new TypeError(); } }
三.语句和表达式
-
花括号对齐方式
建议行尾风格,不推荐次行风格
-
块语句空格
if后的圆括号部分前后各有一个空格,例如:
if (expr) { code }
-
switch语句
-
缩进:case与switch对齐,break缩进1级
-
case贯穿:用空行或注释//falls through表明case贯穿是故意的
-
default:保留default或者用注释//no default表明没有default
P.S.《JavaScript语言精粹》的作者道格拉斯认为不应该用case贯穿(称之为鸡肋),因为极易引发bug,而尼古拉斯认为用空行或者注释说明就好了
-
-
with语句
不用
-
for循环
所有变量都应该在函数体顶部声明,包括for循环初始化部分用到的变量,避免hosting(提升)引发bug(可能会屏蔽全局变量)
-
for-in循环
不要用来遍历数组,用的时候记得加上hasOwnProperty过滤,如果故意遍历原型属性,应该用注释说明
四.变量、函数、操作符
-
变量声明
函数体 = 变量声明 + 函数声明 + 逻辑语句。用空行隔开各个部分
-
函数声明
先声明再使用,千万不要把函数声明放在if分支里,因为浏览器理解不同,而且ES没给标准
-
函数调用
圆括号前后都不加空格,避免和块语句混淆
-
匿名函数立即执行
把立即执行的匿名函数用圆括号包裹,避免与匿名函数声明混淆
-
严格模式
不要在全局作用域开严格模式,只在函数内部开,给多个函数开可以用匿名函数立即执行限定严格模式的作用域
-
判断等于
只用===和!==
-
eval
不用eval()和new Function(),用匿名函数优化setTimeout()和setInterval()
-
基本包装类型
不要用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语言精粹》