Google JavaScript 编码规范指南
修订版: 2.9
Aaron Whyte
Bob Jervis
Dan Pupius
Eric Arvidsson
Fritz Schneider
Robby Walker
英文原版:http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml
中文翻译:http://docs.kissyui.com/docs/html/styleguide/google/javascriptguide.xml
排版整理:li3p AT yahoo.cn
目录
Google JavaScript 编码规范指南 .................................................................................................... 1
背景 .................................................................................................................................................. 3
JavaScript 语言规范 ................................................................................................................... 3
1. 变量 ................................................................................................................................. 3
2. 常量 ................................................................................................................................. 3
3. 分号 ................................................................................................................................. 4
4. 嵌套函数 ......................................................................................................................... 5
5. 块内函数声明 ................................................................................................................. 5
6. 异常 ................................................................................................................................. 5
7. 自定义异常 ..................................................................................................................... 6
8. 标准特性 ......................................................................................................................... 6
9. 封装基本类型 ................................................................................................................. 6
10. 多级原型结构(Multi-level prototype hierarchies) ........................................ 6
11. 方法定义 ..................................................................................................................... 7
12. 闭包 ............................................................................................................................. 7
13.
eval() ......................................................................................................................... 8
14. with() {} ...................................................................................................................... 9
this ............................................................................................................................... 9
15.
16.
for-in 循环 ................................................................................................................. 9
17. 关联数组 ................................................................................................................... 10
18. 多行字符串 ............................................................................................................... 10
19.
Array 和 Object 直接量 ..................................................................................... 11
20. 修改内置对象的原型 ............................................................................................... 12
IE 下的条件注释 ....................................................................................................... 12
21.
Google Style Guide of JavaScript Chinese Version
JavaScript 编码风格 ................................................................................................................. 13
22. 命名 ........................................................................................................................... 13
23. 自定义 toString() 方法 .......................................................................................... 16
24. 延迟初始化 ............................................................................................................... 16
25. 明确作用域 ............................................................................................................... 16
26. 代码格式化 ............................................................................................................... 17
27. 括号 ........................................................................................................................... 21
28. 字符串 ....................................................................................................................... 21
29. 可见性 (私有域和保护域) .................................................................................... 21
30.
JavaScript 类型 ..................................................................................................... 23
31. 注释 ........................................................................................................................... 29
32. 编译 ........................................................................................................................... 45
Tips and Tricks ........................................................................................................ 45
33.
34.
Parting Words ........................................................................................................ 50
Page 2
Google Style Guide of JavaScript Chinese Version
背景
JavaScript 是一种客户端脚本语言, Google 的许多开源工程中都有用到它. 这份指南列
出了编写 JavaScript 时需要遵守的规则.
JavaScript 语言规范
1. 变量
声明变量必须加上 var 关键字.
Decision: 当你没有写 var, 变量就会暴露在全局上下文中, 这样很可能会和现有变量冲突.
另外, 如果没有加上, 很难明确该变量的作用域是什么, 变量也很可能像在局部作用域中,
很轻易地泄漏到 Document 或者 Window 中, 所以务必用 var 去声明变量.
2. 常量
常量的形式如: NAMES_LIKE_THIS, 即使用大写字符, 并用下划线分隔. 你也可用 @const
标记来指明它是一个常量. 但请永远不要使用 const 关键词.
Decision:
对于基本类型的常量, 只需转换命名.
/**
* The number of seconds in a minute.
* @type {number}
*/
goog.example.SECONDS_IN_A_MINUTE = 60;
对于非基本类型, 使用 @const 标记.
/**
* The number of seconds in each of the given units.
* @type {Object.}
* @const
*/
goog.example.SECONDS_TABLE = {
minute: 60,
hour: 60 * 60,
Page 3
Google Style Guide of JavaScript Chinese Version
day: 60 * 60 * 24
}
这标记告诉编译器它是常量.
至于关键词 const, 因为 IE 不能识别, 所以不要使用.
3. 分号
总是使用分号.
如果仅依靠语句间的隐式分隔, 有时会很麻烦. 你自己更能清楚哪里是语句的起止.
而且有些情况下, 漏掉分号会很危险:
// 1.
MyClass.prototype.myMethod = function() {
return 42;
} // No semicolon here.
(function() {
// Some initialization code wrapped in a function to create a scope for locals.
})();
var x = {
'i': 1,
'j': 2
} // No semicolon here.
// 2. Trying to do one thing on Internet Explorer and another on Firefox.
// I know you'd never write code like this, but throw me a bone.
[normalVersion, ffVersion][isIE]();
var THINGS_TO_EAT = [apples, oysters, sprayOnCheese] // No semicolon here.
// 3. conditional execution a la bash
-1 == resultOfOperation() || die();
这段代码会发生些什么诡异事呢?
Page 4
Google Style Guide of JavaScript Chinese Version
1. 报 JavaScript 错误 - 例子 1 上的语句会解释成, 一个函数带一匿名函数作为参数而被
调用, 返回 42 后, 又一次被"调用", 这就导致了错误.
2. 例子 2 中, 你很可能会在运行时遇到 'no such property in undefined' 错误, 原因是代
码试图这样 x[ffVersion][isIE]() 执行.
3. 当 resultOfOperation() 返回非 NaN 时, 就会调用 die, 其结果也会赋给
THINGS_TO_EAT.
为什么?
JavaScript 的语句以分号作为结束符, 除非可以非常准确推断某结束位置才会省略分号. 上面
的几个例子产出错误, 均是在语句中声明了函数/对象/数组直接量, 但 闭括号('}'或']')并不足以
表示该语句的结束. 在 JavaScript 中, 只有当语句后的下一个符号是后缀或括号运算符时, 才
会认为该语句的结束.
遗漏分号有时会出现很奇怪的结果, 所以确保语句以分号结束.
4. 嵌套函数
可以使用
嵌套函数很有用, 比如,减少重复代码, 隐藏帮助函数, 等. 没什么其他需要注意的地方, 随意使
用.
5. 块内函数声明
不要在块内声明一个函数
不要写成:
if (x) {
function foo() {}
}
虽然很多 JS 引擎都支持块内声明函数, 但它不属于 ECMAScript 规范 (见 ECMA-262, 第
13 和 14 条). 各个浏览器糟糕的实现相互不兼容, 有些也与未来 ECMAScript 草案相违背.
ECMAScript 只允许在脚本的根语句或函数中声明函数. 如果确实需要在块中定义函数, 建议
使用函数表达式来初始化变量:
if (x) {
var foo = function() {}
}
6. 异常
Page 5
Google Style Guide of JavaScript Chinese Version
可以使用
你在写一个比较复杂的应用时, 不可能完全避免不会发生任何异常. 大胆去用吧.
7. 自定义异常
可以使用
有时发生异常了, 但返回的错误信息比较奇怪, 也不易读. 虽然可以将含错误信息的引用对象或
者可能产生错误的完整对象传递过来, 但这样做都不是很好, 最好还是自定义异常类, 其实这些
基本上都是最原始的异常处理技巧. 所以在适当的时候使用自定义异常.
8. 标准特性
总是优于非标准特性.
最大化可移植性和兼容性, 尽量使用标准方法而不是用非标准方法, (比如, 优先用
string.charAt(3) 而不用 string[3] , 通过 DOM 原生函数访问元素, 而不是使用应
用封装好的快速接口.
9. 封装基本类型
不要
没有任何理由去封装基本类型, 另外还存在一些风险:
var x = new Boolean(false);
if (x) {
alert('hi'); // Shows 'hi'.
}
除非明确用于类型转换, 其他情况请千万不要这样做!
var x = Boolean(0);
if (x) {
alert('hi'); // This will never be alerted.
}
typeof Boolean(0) == 'boolean';
typeof new Boolean(0) == 'object';
有时用作 number, string 或 boolean 时, 类型的转换会非常实用.
10. 多级原型结构(Multi-level prototype hierarchies)
Page 6
Google Style Guide of JavaScript Chinese Version
不是首选
多级原型结构是指 JavaScript 中的继承关系. 当你自定义一个 D 类, 且把 B 类作为其原型, 那
么这就获得了一个多级原型结构. 这些原型结构会变得越来越复杂!
使用 the Closure 库 中的 goog.inherits() 或其他类似的用于继承的函数, 会是更好的
选择.
function D() {
goog.base(this)
}
goog.inherits(D, B);
D.prototype.method = function() {
...
};
11. 方法定义
Foo.prototype.bar = function() { ... };
有很多方法可以给构造器添加方法或成员, 我们更倾向于使用如下的形式:
Foo.prototype.bar = function() {
/* ... */
};
12. 闭包
可以, 但小心使用.
闭包也许是 JS 中最有用的特性了. 有一份比较好的介绍闭包原理的文档.
有一点需要牢记, 闭包保留了一个指向它封闭作用域的指针, 所以, 在给 DOM 元素附加闭包
时, 很可能会产生循环引用, 进一步导致内存泄漏. 比如下面的代码:
function foo(element, a, b) {
element.onclick = function() { /* uses a and b */ };
}
这里, 即使没有使用 element, 闭包也保留了 element, a 和 b 的引用, . 由于 element
也保留了对闭包的引用, 这就产生了循环引用, 这就不能被 GC 回收. 这种情况下, 可将代码
重构为:
Page 7
Google Style Guide of JavaScript Chinese Version
function foo(element, a, b) {
element.onclick = bar(a, b);
}
function bar(a, b) {
return function() { /* uses a and b */ }
}
13. eval()
只用于解析序列化串 (如: 解析 RPC 响应)
eval() 会让程序执行的比较混乱, 当 eval() 里面包含用户输入的话就更加危险. 可以用其
他更佳的, 更清晰, 更安全的方式写你的代码, 所以一般情况下请不要使用 eval(). 当碰到一些
需要解析序列化串的情况下(如, 计算 RPC 响应), 使用 eval 很容易实现.
解析序列化串是指将字节流转换成内存中的数据结构. 比如, 你可能会将一个对象输出成文件
形式:
users = [
{
name: 'Eric',
id: 37824,
email: 'jellyvore@myway.com'
},
{
name: 'xtof',
id: 31337,
email: 'b4d455h4x0r@google.com'
},
...
];
很简单地调用 eval 后, 把表示成文件的数据读取回内存中.
类似的, eval() 对 RPC 响应值进行解码. 例如, 你在使用 XMLHttpRequest 发出一个
RPC 请求后, 通过 eval () 将服务端的响应文本转成 JavaScript 对象:
var userOnline = false;
var user = 'nusrat';
var xmlhttp = new XMLHttpRequest();
xmlhttp.open('GET', 'http://chat.google.com/isUserOnline?user=' +
user, false);
xmlhttp.send('');
// Server returns:
// userOnline = true;
if (xmlhttp.status == 200) {
Page 8