原文: [url=http://javascript.crockford.com/code.html]Code Conentions for the JavaScript Programming Language[/url]
这是一篇JavaScript编程代码规范,它由Sun公司的文档[url=http://java.sun.com/docs/codeconv/]Code Conventions for the Java Programming Language[/url]激发而来。
由于[url=http://javascript.crockford.com/javascript.html]JavaScript is not Java[/url],这篇规范和Java规范相比有很大改动。
代码质量在软件质量中占很大比例。在软件生命周期里,一个程序会被许多人接手。如果一个程序可以很好的表达自己的结构和特性,则在
不久的将来修改它时就会减少程序崩溃的可能。
代码规范可以帮助减少程序的脆弱性。
我们所有的JavaScript代码都直接发布给公众,它应该具有发布质量。
Neatness counts.
[b]
目录:
JavaScript文件
缩进
行宽
注释
变量声明
方法声明
命名
语句
- 简单语句
- 复合语句
- 标签
- return语句
- if语句
- for语句
- while语句
- do语句
- switch语句
- try语句
- continue语句
- with语句
空格
额外的建议
- {}和[]
- 逗号操作符
- 块作用域
- 赋值表达式
- ===和!==操作符
- 令人混淆的加和减
- 邪恶的eval
[/b]
[color=blue][b]JavaScript文件[/b][/color]
JavaScript程序应该作为一个.js文件存储和发布。
JavaScript代码不应该嵌入在HTML文件里,除非那些代码是一个单独的会话特有的。HTML里的JavaScript代码大大增加了页面的大小,并且
很难通过缓存和压缩来缓解。
<script src=filename.js>标签应该在body里越靠后的位置越好。这减少了由于加载script而导致的其它页面组件的延迟。[b]没有必要使用
language或者type属性。由服务器而不是script标签来决定MIME类型。[/b]
[color=blue][b]缩进[/b][/color]
缩进的最小单位是4个空格。不要使用tab键,because (as of this writing in the 21st Century) there still is not a standard
for the placement of tabstops. 使用空格会引起文件变大,但是这点大小对局域网无关紧要,而且差别被[url=http://yuiblog.com/blog/2006/03/06/minification-v-obfuscation/]minification[/url]消除了。
[color=blue][b]行宽[/b][/color]
不要让一行代码超过80个字符。当一条语句不能在单独一行写完时,可能有必要拆分它。在操作符后进行拆分,最好是在逗号后面拆分。
操作符后面进行拆分减少了通过插入分号伪装copy-paste错误的可能性。下一行应该缩进8个空格。
[color=blue][b]注释[/b][/color]
慷慨的写注释。留下一些供需要理解你做了什么的人们(可能是你自己)下次阅读的信息是有用的。注释应该书写良好和清晰,就像它们
标注的代码一样。偶尔小幽默一把也是可以的。挫折和怨恨就别写了。
更新注释非常重要。错误的注释让程序更难读懂和理解。
让注释有意义。更多的关注于不能马上可见的东西。不要用如下内容浪费读者的时间:
[code]
i = 0; // Set i to zero.
[/code]
一般使用行注释。把块注释用于正式文档或外部注释。
[color=blue][b]变量声明[/b][/color]
所有的变量应该在使用前声明。JavaScript不强求这点,但是这样做会让程序更易读,并且会让探测未声明的可能变成隐式的[url=http://yuiblog.com/blog/2006/06/01/global-domination/]globals[/url]的
变量更容易。
var语句应该为方法体内的第一个语句。
每个变量声明应该自己占一行并有注释。它们应该按字母顺序排列。
[code]
var currentEntry; // currentyly selected table entry
var level; // indentation level
var size; // size of table
[/code]
JavaScript没有块作用域,所以在块里定义变量可能会让有其它C家族语言经验的程序员迷惑。在方法顶端定义所有变量。
尽量少使用全局变量。隐式的全局变量应该从来不使用。
[color=blue][b]方法声明[/b][/color]
所有的方法应该在它们使用前声明。内部方法应该位于var语句后面。这让哪些变量包含在它的scope里更清楚。
方法名和参数列表的“(”(左圆括号)之间不应该有空格。在“)”(右圆括号)和“{”(左大括号)之间有一个空格。
方法体本身缩进4个空格。“}”(右大括号)应该和方法声明处对齐。
[code]
function outer(c, d) {
var e = c * d;
function inner(a, b) {
return (e * a) + b;
}
return inner(0, 1);
}
[/code]
这个规范可以和JavaScript很好的工作,因为在JavaScript里方法和对象字面量可以放在允许表达式的任何位置。它使用内部方法和复杂
结构提供最好的可读性。
[code]
function getElementsByClassName(className) {
var results = [];
walkTheDOM(document.body, function (node) {
var a; // array of class names
var c = node.className; // the node's classname
var i; // loop counter
// If the node has a class name, then split it into a list of simple names.
// If any of them match the requested name, then append the node to the set of results.
if (c) {
a = c.split(' ');
for (i = 0; i < a.length; i += 1) {
if (a[i] === className) {
results.push(node);
break;
}
}
}
});
return results;
}
[/code]
如果一个方法字面量为匿名的,则在“function”和“(”(左圆括号)之间应该有一个空格。如果省略空格,则它可能看起来方法名是
“function”,而这是错误的。
[code]
div.onclick = function (e) {
return false;
};
that = {
method: function () {
return this.datum;
},
datum: 0;
};
[/code]
尽量少用全局方法。
[color=blue][b]命名[/b][/color]
命名应该由26个大小写字母(A .. Z, a .. z),10个数字(0 .. 9)和_(下划线)组成。不要使用国际字符,因为它们可能不易读或者不能在
任何地方都能容易理解。不要在名字里使用$(美元符号)或\(反斜线符号)。
不要使用_(下划线)作为名字的首字母。它有时被用来表示私有,但是它实际上不提供私有性。
如果私有性很重要,使用提供私有性的[url=http://javascript.crockford.com/private.html]private members[/url]。
Avoid conventions that demonstrate a lack of competence.
大多数变量和方法名应该以小写字母开始。
必须使用[url=http://yuiblog.com/blog/2006/11/13/javascript-we-hardly-new-ya/]new[/url]前缀的构造函数应该以大写字母开始。JavaScript不会在省略new时报编译期警告或运行时警告。
不使用new时会发生坏事情,所以大写首字母规范是我们拥有的唯一的防御。
全局变量应该全部使用大写字母。(JavaScript没有宏或常量,所以没有多少要求使用大写字母来表示JavaScript的特性的场景)
[color=blue][b]语句[/b][/color]
[b]简单语句[/b]
每行应该包含至少一个语句。在每个简单语句末尾添加一个“;”(分号)。注意一个给方法字面量或对象字面量赋值的赋值语句仍然是
一个赋值语句,所以也必须以分号结尾。
JavaScript允许任何表达式作为语句使用。这可能产生一些错误,特别是在插入分号时。唯一可以当作语句使用的表达式是赋值表达式和
调用表达式。
[b]复合语句[/b]
复合语句是包含一个用“{}”(大括号)包围语句列表的的语句。
1,包围的语句应该再缩进4个空格。
2,“{”(左大括号)应该位于开始复合语句的行的末尾。
3,“}”(右大括号)应该新起一行并且和相匹配的“{”所在那行的起始位置对齐
4,当语句是控制结构的一部分时,所有语句都应该用括号包围,即使是单行语句,例如if或for语句。这让添加语句更容易而且不会引起八哥。
[b]标签[/b]
语句标签是可选的。只有如下语句需要被标签标识: while,do,for,switch。
[b]return语句[/b]
具有值的return语句不应该使用“()”(圆括号)包围值。返回值表达式必须和return关键字在同一行从而避免插入分号。
[b]if语句[/b]
if语句应该使用如下格式:
[code]
if (condition) {
statements;
}
if (condition) {
statements;
} else {
statements;
}
if (condition) {
statements;
} else if (condition) {
statements;
} else {
statements;
}
[/code]
[b]for语句[/b]
for语句应该使用如下格式:
[code]
for (initialization; condition; update) {
statements;
}
for (variable in object) {
statements;
}
[/code]
第一种格式应该和数组使用。
第二种格式应该和对象使用。注意添加到对象的prototype中的成员将被包含在遍历中。通过使用hasOwnProperty方法来区分对象的
成员是明智的:
[code]
for (variable in object) {
if (object.hasOwnProperty()) {
statements;
}
}
[/code]
[b]while语句[/b]
while语句应该使用如下格式:
[code]
while (condition) {
statements;
}
[/code]
[b]do语句[/b]
do语句应该使用如下格式:
[code]
do {
statements;
} while (condition);
[/code]
不像其它复合语句,do语句始终使用“;”(分号)结尾。
[b]switch语句[/b]
switch语句应该有如下格式:
[code]
switch (expression) {
case expression:
statements;
default:
statements;
}
[/code]
每个case和switch对齐,这避免了缩进过度。
每组语句(除了default)应该以break,return或者throw结束。不要fall through。
[b]try语句[/b]
try语句应该使用如下格式:
[code]
try {
statements;
} catch (variable) {
statements;
}
try {
statements;
} catch (variable) {
statements;
} finally {
statements;
}
[/code]
[b]continue语句[/b]
不要使用continue语句。它会让方法的控制流程模糊。
[b]with语句[/b]
[url=http://yuiblog.com/blog/2006/04/11/with-statement-considered-harmful/]不要使用with语句[/url]。
[color=blue][b]空格[/b][/color]
空行通过将逻辑相关的代码放到一起来增加可读性。
空格应该用于如下情况:
1,关键字后面跟“(”(左圆括号)时应该用一个空格隔开。
[code]
while (true) {
[/code]
2,方法名和方法的“(”(左圆括号)之间不要有空格。这利于区分关键字和方法调用。
3,所有的二元操作符,除了“.”(圆点)、“(”(左圆括号)和“[”(左中括号),都应该使用一个空格来和操作数隔开。
4,一元操作符和操作数之间不应该使用空格隔开,除了操作符是一个单词时,如typeof。
5,for语句控制部分的每个“;”(分号)应该在后面跟一个空格。
6,每个“,”(逗号)后面应该跟一个空格。
[color=blue][b]额外的建议[/b][/color]
[b]{}和[][/b]
使用{}替代new Object()。使用[]替代new Array()。
当成员名字为连续的整数时使用数组。当成员名字为任意的字符串或名字时使用对象。
[b]逗号操作符[/b]
不要使用逗号操作符,除了for语句的控制部分的严格使用。(这不适合逗号操作符,它应该用于对象字面量,数组字面量,var语句和参数
列表。)
[b]块作用域[/b]
在JavaScript里块没有作用域,只有方法有作用域。不要使用块,除了复合语句一定需要用到外。
[b]赋值表达式[/b]
不要在if和while语句的条件部分做赋值。不要写不易懂的代码。
[b]===和!==操作符[/b]
始终使用===和!==操作符会更好。==和!=操作符会做类型强制转换。特别是,不要使用==来和“假”值做比较。
[b]令人混淆的加和减[/b]
注意不要在“+”后面跟“+”或“++”。这种模式令人混淆。在它们之间插入圆括号来让你的意图更清晰。
[code]
total = subtotal + +myInput.value;
// is better written as
total = subtotal + (+myInput.value);
[/code]
这样“+ +”就不会被读错成“++”。
[b]邪恶的eval[/b]
eval方法是JavaScript里最滥用的特性。不要使用它。
eval有别名。不要使用Function构造函数。不要传递字符串给setTimeout或者setInterval。
这是一篇JavaScript编程代码规范,它由Sun公司的文档[url=http://java.sun.com/docs/codeconv/]Code Conventions for the Java Programming Language[/url]激发而来。
由于[url=http://javascript.crockford.com/javascript.html]JavaScript is not Java[/url],这篇规范和Java规范相比有很大改动。
代码质量在软件质量中占很大比例。在软件生命周期里,一个程序会被许多人接手。如果一个程序可以很好的表达自己的结构和特性,则在
不久的将来修改它时就会减少程序崩溃的可能。
代码规范可以帮助减少程序的脆弱性。
我们所有的JavaScript代码都直接发布给公众,它应该具有发布质量。
Neatness counts.
[b]
目录:
JavaScript文件
缩进
行宽
注释
变量声明
方法声明
命名
语句
- 简单语句
- 复合语句
- 标签
- return语句
- if语句
- for语句
- while语句
- do语句
- switch语句
- try语句
- continue语句
- with语句
空格
额外的建议
- {}和[]
- 逗号操作符
- 块作用域
- 赋值表达式
- ===和!==操作符
- 令人混淆的加和减
- 邪恶的eval
[/b]
[color=blue][b]JavaScript文件[/b][/color]
JavaScript程序应该作为一个.js文件存储和发布。
JavaScript代码不应该嵌入在HTML文件里,除非那些代码是一个单独的会话特有的。HTML里的JavaScript代码大大增加了页面的大小,并且
很难通过缓存和压缩来缓解。
<script src=filename.js>标签应该在body里越靠后的位置越好。这减少了由于加载script而导致的其它页面组件的延迟。[b]没有必要使用
language或者type属性。由服务器而不是script标签来决定MIME类型。[/b]
[color=blue][b]缩进[/b][/color]
缩进的最小单位是4个空格。不要使用tab键,because (as of this writing in the 21st Century) there still is not a standard
for the placement of tabstops. 使用空格会引起文件变大,但是这点大小对局域网无关紧要,而且差别被[url=http://yuiblog.com/blog/2006/03/06/minification-v-obfuscation/]minification[/url]消除了。
[color=blue][b]行宽[/b][/color]
不要让一行代码超过80个字符。当一条语句不能在单独一行写完时,可能有必要拆分它。在操作符后进行拆分,最好是在逗号后面拆分。
操作符后面进行拆分减少了通过插入分号伪装copy-paste错误的可能性。下一行应该缩进8个空格。
[color=blue][b]注释[/b][/color]
慷慨的写注释。留下一些供需要理解你做了什么的人们(可能是你自己)下次阅读的信息是有用的。注释应该书写良好和清晰,就像它们
标注的代码一样。偶尔小幽默一把也是可以的。挫折和怨恨就别写了。
更新注释非常重要。错误的注释让程序更难读懂和理解。
让注释有意义。更多的关注于不能马上可见的东西。不要用如下内容浪费读者的时间:
[code]
i = 0; // Set i to zero.
[/code]
一般使用行注释。把块注释用于正式文档或外部注释。
[color=blue][b]变量声明[/b][/color]
所有的变量应该在使用前声明。JavaScript不强求这点,但是这样做会让程序更易读,并且会让探测未声明的可能变成隐式的[url=http://yuiblog.com/blog/2006/06/01/global-domination/]globals[/url]的
变量更容易。
var语句应该为方法体内的第一个语句。
每个变量声明应该自己占一行并有注释。它们应该按字母顺序排列。
[code]
var currentEntry; // currentyly selected table entry
var level; // indentation level
var size; // size of table
[/code]
JavaScript没有块作用域,所以在块里定义变量可能会让有其它C家族语言经验的程序员迷惑。在方法顶端定义所有变量。
尽量少使用全局变量。隐式的全局变量应该从来不使用。
[color=blue][b]方法声明[/b][/color]
所有的方法应该在它们使用前声明。内部方法应该位于var语句后面。这让哪些变量包含在它的scope里更清楚。
方法名和参数列表的“(”(左圆括号)之间不应该有空格。在“)”(右圆括号)和“{”(左大括号)之间有一个空格。
方法体本身缩进4个空格。“}”(右大括号)应该和方法声明处对齐。
[code]
function outer(c, d) {
var e = c * d;
function inner(a, b) {
return (e * a) + b;
}
return inner(0, 1);
}
[/code]
这个规范可以和JavaScript很好的工作,因为在JavaScript里方法和对象字面量可以放在允许表达式的任何位置。它使用内部方法和复杂
结构提供最好的可读性。
[code]
function getElementsByClassName(className) {
var results = [];
walkTheDOM(document.body, function (node) {
var a; // array of class names
var c = node.className; // the node's classname
var i; // loop counter
// If the node has a class name, then split it into a list of simple names.
// If any of them match the requested name, then append the node to the set of results.
if (c) {
a = c.split(' ');
for (i = 0; i < a.length; i += 1) {
if (a[i] === className) {
results.push(node);
break;
}
}
}
});
return results;
}
[/code]
如果一个方法字面量为匿名的,则在“function”和“(”(左圆括号)之间应该有一个空格。如果省略空格,则它可能看起来方法名是
“function”,而这是错误的。
[code]
div.onclick = function (e) {
return false;
};
that = {
method: function () {
return this.datum;
},
datum: 0;
};
[/code]
尽量少用全局方法。
[color=blue][b]命名[/b][/color]
命名应该由26个大小写字母(A .. Z, a .. z),10个数字(0 .. 9)和_(下划线)组成。不要使用国际字符,因为它们可能不易读或者不能在
任何地方都能容易理解。不要在名字里使用$(美元符号)或\(反斜线符号)。
不要使用_(下划线)作为名字的首字母。它有时被用来表示私有,但是它实际上不提供私有性。
如果私有性很重要,使用提供私有性的[url=http://javascript.crockford.com/private.html]private members[/url]。
Avoid conventions that demonstrate a lack of competence.
大多数变量和方法名应该以小写字母开始。
必须使用[url=http://yuiblog.com/blog/2006/11/13/javascript-we-hardly-new-ya/]new[/url]前缀的构造函数应该以大写字母开始。JavaScript不会在省略new时报编译期警告或运行时警告。
不使用new时会发生坏事情,所以大写首字母规范是我们拥有的唯一的防御。
全局变量应该全部使用大写字母。(JavaScript没有宏或常量,所以没有多少要求使用大写字母来表示JavaScript的特性的场景)
[color=blue][b]语句[/b][/color]
[b]简单语句[/b]
每行应该包含至少一个语句。在每个简单语句末尾添加一个“;”(分号)。注意一个给方法字面量或对象字面量赋值的赋值语句仍然是
一个赋值语句,所以也必须以分号结尾。
JavaScript允许任何表达式作为语句使用。这可能产生一些错误,特别是在插入分号时。唯一可以当作语句使用的表达式是赋值表达式和
调用表达式。
[b]复合语句[/b]
复合语句是包含一个用“{}”(大括号)包围语句列表的的语句。
1,包围的语句应该再缩进4个空格。
2,“{”(左大括号)应该位于开始复合语句的行的末尾。
3,“}”(右大括号)应该新起一行并且和相匹配的“{”所在那行的起始位置对齐
4,当语句是控制结构的一部分时,所有语句都应该用括号包围,即使是单行语句,例如if或for语句。这让添加语句更容易而且不会引起八哥。
[b]标签[/b]
语句标签是可选的。只有如下语句需要被标签标识: while,do,for,switch。
[b]return语句[/b]
具有值的return语句不应该使用“()”(圆括号)包围值。返回值表达式必须和return关键字在同一行从而避免插入分号。
[b]if语句[/b]
if语句应该使用如下格式:
[code]
if (condition) {
statements;
}
if (condition) {
statements;
} else {
statements;
}
if (condition) {
statements;
} else if (condition) {
statements;
} else {
statements;
}
[/code]
[b]for语句[/b]
for语句应该使用如下格式:
[code]
for (initialization; condition; update) {
statements;
}
for (variable in object) {
statements;
}
[/code]
第一种格式应该和数组使用。
第二种格式应该和对象使用。注意添加到对象的prototype中的成员将被包含在遍历中。通过使用hasOwnProperty方法来区分对象的
成员是明智的:
[code]
for (variable in object) {
if (object.hasOwnProperty()) {
statements;
}
}
[/code]
[b]while语句[/b]
while语句应该使用如下格式:
[code]
while (condition) {
statements;
}
[/code]
[b]do语句[/b]
do语句应该使用如下格式:
[code]
do {
statements;
} while (condition);
[/code]
不像其它复合语句,do语句始终使用“;”(分号)结尾。
[b]switch语句[/b]
switch语句应该有如下格式:
[code]
switch (expression) {
case expression:
statements;
default:
statements;
}
[/code]
每个case和switch对齐,这避免了缩进过度。
每组语句(除了default)应该以break,return或者throw结束。不要fall through。
[b]try语句[/b]
try语句应该使用如下格式:
[code]
try {
statements;
} catch (variable) {
statements;
}
try {
statements;
} catch (variable) {
statements;
} finally {
statements;
}
[/code]
[b]continue语句[/b]
不要使用continue语句。它会让方法的控制流程模糊。
[b]with语句[/b]
[url=http://yuiblog.com/blog/2006/04/11/with-statement-considered-harmful/]不要使用with语句[/url]。
[color=blue][b]空格[/b][/color]
空行通过将逻辑相关的代码放到一起来增加可读性。
空格应该用于如下情况:
1,关键字后面跟“(”(左圆括号)时应该用一个空格隔开。
[code]
while (true) {
[/code]
2,方法名和方法的“(”(左圆括号)之间不要有空格。这利于区分关键字和方法调用。
3,所有的二元操作符,除了“.”(圆点)、“(”(左圆括号)和“[”(左中括号),都应该使用一个空格来和操作数隔开。
4,一元操作符和操作数之间不应该使用空格隔开,除了操作符是一个单词时,如typeof。
5,for语句控制部分的每个“;”(分号)应该在后面跟一个空格。
6,每个“,”(逗号)后面应该跟一个空格。
[color=blue][b]额外的建议[/b][/color]
[b]{}和[][/b]
使用{}替代new Object()。使用[]替代new Array()。
当成员名字为连续的整数时使用数组。当成员名字为任意的字符串或名字时使用对象。
[b]逗号操作符[/b]
不要使用逗号操作符,除了for语句的控制部分的严格使用。(这不适合逗号操作符,它应该用于对象字面量,数组字面量,var语句和参数
列表。)
[b]块作用域[/b]
在JavaScript里块没有作用域,只有方法有作用域。不要使用块,除了复合语句一定需要用到外。
[b]赋值表达式[/b]
不要在if和while语句的条件部分做赋值。不要写不易懂的代码。
[b]===和!==操作符[/b]
始终使用===和!==操作符会更好。==和!=操作符会做类型强制转换。特别是,不要使用==来和“假”值做比较。
[b]令人混淆的加和减[/b]
注意不要在“+”后面跟“+”或“++”。这种模式令人混淆。在它们之间插入圆括号来让你的意图更清晰。
[code]
total = subtotal + +myInput.value;
// is better written as
total = subtotal + (+myInput.value);
[/code]
这样“+ +”就不会被读错成“++”。
[b]邪恶的eval[/b]
eval方法是JavaScript里最滥用的特性。不要使用它。
eval有别名。不要使用Function构造函数。不要传递字符串给setTimeout或者setInterval。