|
30 | 30 | ### 我并不想强制别人在其代码或项目中使用我个人所偏好的代码风格;如果已经存在一个通用编码规范,它必须受到尊崇。
|
31 | 31 |
|
32 | 32 |
|
33 |
| -> ### "对风格的挑刺毫无无意义可言。他们必须是指导原则,且你必须遵循。" |
| 33 | +> ### "对风格的挑刺毫无无意义可言。它们必须是指导原则,且你必须遵循。" |
34 | 34 | >_Rebecca_ _Murphey_
|
35 | 35 |
|
36 | 36 |
|
37 | 37 |
|
38 |
| -> ### "成为一个优秀的成功项目管理者的一个条件是明白,按自己的偏好风格写代码是非常不好的做法。如果成千上万的人都在使用你的代码,那么请尽可能通俗易懂地写出你的代码,而非在规范之下自作聪明地使用自己偏好的风格。" |
| 38 | +> ### "成为一个优秀的成功项目管理者的一个条件是,明白按自己的偏好风格写代码是非常不好的做法。如果成千上万的人都在使用你的代码,那么请尽可能通俗易懂地写出你的代码,而非在规范之下自作聪明地使用自己偏好的风格。" |
39 | 39 | >_Idan_ _Gazit_
|
40 | 40 |
|
41 | 41 | ## 翻译版本
|
|
53 | 53 |
|
54 | 54 | ## 重要,非常通用资源:
|
55 | 55 |
|
56 |
| -### 代码质量工具,资源和文献 |
| 56 | +### 代码质量工具、资源和文献 |
57 | 57 |
|
58 | 58 | * [JavaScript Plugin](http://docs.codehaus.org/display/SONAR/JavaScript+Plugin) for [Sonar](http://www.sonarsource.org/)
|
59 | 59 | * [jsPerf](http://jsperf.com/)
|
|
68 | 68 | ### [ECMAScript 5.1 注解版](http://es5.github.com/)
|
69 | 69 | ### [EcmaScript 语言规范, 5.1 版](http://ecma-international.org/ecma-262/5.1/)
|
70 | 70 |
|
71 |
| -如下列文档的现实是:1)不完全版,2)*必读*。我并不全(不总是,always agree)赞同下列所有作者所写的风格,但有一点可以确定的是:他们具备一致性。除此之外,他们还都是这门语言的权威人士。 |
| 71 | +下列文档的现实是:1)不完全版,2)*必读*。我并不全(不总是,always agree)赞同下列所有作者所写的风格,但有一点可以确定的是:他们具备一致性。除此之外,他们还都是这门语言的权威人士。 |
72 | 72 |
|
73 | 73 | * [Baseline For Front End Developers](http://rmurphey.com/blog/2012/04/12/a-baseline-for-front-end-developers/)
|
74 | 74 | * [Eloquent JavaScript](http://eloquentjavascript.net/)
|
|
85 | 85 |
|
86 | 86 | ### 测试工具
|
87 | 87 |
|
88 |
| -项目 _必须_ 包括某此类型的单元、引用、实现或者功能性测试。使用代码示例并不足以称为“测试”。下面是一系列测试框架,他们谁都不是谁的更好替代品(which are endorsed more than the other)。 |
| 88 | +项目 _必须_ 包括某此类型的单元、引用、实现或者功能性测试。使用代码示例并不足以称为“测试”。下面是一系列测试框架,他们只代表自己(谁都不是谁的更好替代品,which are endorsed more than the other)。 |
89 | 89 |
|
90 | 90 | * [QUnit](http://github.com/jquery/qunit)
|
91 | 91 | * [Jasmine](https://github.com/pivotal/jasmine)
|
|
115 | 115 |
|
116 | 116 | 下面的章节描述的是一个 _合理_ 的现代 JavaScript 开发风格指南,并非硬性规定。其想送出的核心理念是*高度统一的代码风格*(the law of code style consistency)。你为项目所择风格都应为最高准则。作为一个描述放置于你的项目中,并链接到这个文档作为代码风格一致性、可读性和可维护性的保证。
|
117 | 117 |
|
118 |
| -## Idiomatic Style Manifesto |
| 118 | +## Idiomatic 风格宣言 |
119 | 119 |
|
120 | 120 | 1. <a name="whitespace">空白</a>
|
121 | 121 | - 永远都不要混用空格和Tab。
|
122 |
| - - 开始一个项目,在写代码之前,选择软缩进(空格)或者 Tab(作为缩进方式),以将其作为**最高准则**。 |
123 |
| - - 为了可读, 我总是推荐在你的编辑中中设计2个字母的缩进 — 这等同于两个空格或者两个空格替代一个 Tab。 |
| 122 | + - 开始一个项目,在写代码之前,选择软缩进(空格)或者 Tab(作为缩进方式),并将其作为**最高准则**。 |
| 123 | + - 为了可读, 我总是推荐在你的编辑中设计2个字母的缩进 — 这等同于两个空格或者两个空格替代一个 Tab。 |
124 | 124 | - 如果你的编辑器支持,请总是打开 “显示不可见字符” 这个设置。好处是:
|
125 | 125 | - 保证一致性
|
126 |
| - - 消灭行末的空格 |
127 |
| - - 消灭空行的空格 |
| 126 | + - 去掉行末的空格 |
| 127 | + - 去掉空行的空格 |
128 | 128 | - 提交和对比更具可读性
|
129 | 129 |
|
130 | 130 |
|
131 |
| -2. <a name="spacing">Beautiful Syntax</a> |
| 131 | +2. <a name="spacing">美化语法</a> |
132 | 132 |
|
133 | 133 | A. 小括号, 花括号, 换行
|
134 | 134 |
|
|
151 | 151 | // 使用空格来提升可读性
|
152 | 152 |
|
153 | 153 | if ( condition ) {
|
154 |
| - // statements |
| 154 | + // 语句 |
155 | 155 | }
|
156 | 156 |
|
157 | 157 | while ( condition ) {
|
158 |
| - // statements |
| 158 | + // 语句 |
159 | 159 | }
|
160 | 160 |
|
161 | 161 | for ( var i = 0; i < 100; i++ ) {
|
162 |
| - // statements |
| 162 | + // 语句 |
163 | 163 | }
|
164 | 164 |
|
165 | 165 | // 更好的做法:
|
|
168 | 168 | length = 100;
|
169 | 169 |
|
170 | 170 | for ( i = 0; i < length; i++ ) {
|
171 |
| - // statements |
| 171 | + // 语句 |
172 | 172 | }
|
173 | 173 |
|
174 | 174 | // 或者...
|
|
177 | 177 | length = 100;
|
178 | 178 |
|
179 | 179 | for ( ; i < length; i++ ) {
|
180 |
| - // statements |
| 180 | + // 语句 |
181 | 181 | }
|
182 | 182 |
|
183 | 183 | var prop;
|
184 | 184 |
|
185 | 185 | for ( prop in object ) {
|
186 |
| - // statements |
| 186 | + // 语句 |
187 | 187 | }
|
188 | 188 |
|
189 | 189 |
|
190 | 190 | if ( true ) {
|
191 |
| - // statements |
| 191 | + // 语句 |
192 | 192 | } else {
|
193 |
| - // statements |
| 193 | + // 语句 |
194 | 194 | }
|
195 | 195 | ```
|
196 | 196 |
|
|
286 | 286 | // 2.B.2.3
|
287 | 287 | // 函数表达式
|
288 | 288 | var square = function( number ) {
|
289 |
| - // 返回有价值的、相关的东西 |
| 289 | + // 返回有价值的、相关的内容 |
290 | 290 | return number * number;
|
291 | 291 | };
|
292 | 292 |
|
293 |
| - // 带标记符的函数表达式 |
| 293 | + // 带标识符的函数表达式 |
294 | 294 | // 这种首选形式有附加的功能让其可以调用自身
|
295 | 295 | // 并且在堆栈中有标识符
|
296 | 296 | var factorial = function factorial( number ) {
|
|
357 | 357 | // 2.D.1.1
|
358 | 358 |
|
359 | 359 | if (condition) {
|
360 |
| - // statements |
| 360 | + // 语句 |
361 | 361 | }
|
362 | 362 |
|
363 | 363 | while (condition) {
|
364 |
| - // statements |
| 364 | + // 语句 |
365 | 365 | }
|
366 | 366 |
|
367 | 367 | for (var i = 0; i < 100; i++) {
|
368 |
| - // statements |
| 368 | + // 语句 |
369 | 369 | }
|
370 | 370 |
|
371 | 371 | if (true) {
|
372 |
| - // statements |
| 372 | + // 语句 |
373 | 373 | } else {
|
374 |
| - // statements |
| 374 | + // 语句 |
375 | 375 | }
|
376 | 376 |
|
377 | 377 | ```
|
378 | 378 |
|
379 | 379 | E. 引号
|
380 | 380 |
|
381 |
| - 无论你选择单引号还是双引号都无所谓,在 JavaScript 中它们在解析上没有区别. 而**绝对需要**强制的是一致性。 **永远不要在同一个项目中混用两种引号,选择一种,并保持一致**。 |
| 381 | + 无论你选择单引号还是双引号都无所谓,在 JavaScript 中它们在解析上没有区别。而**绝对需要**强制的是一致性。 **永远不要在同一个项目中混用两种引号,选择一种,并保持一致**。 |
382 | 382 |
|
383 | 383 | F. 行末和空行
|
384 | 384 |
|
|
437 | 437 | object.hasOwnProperty( prop )
|
438 | 438 | "prop" in object
|
439 | 439 |
|
440 |
| - B. 类型转换(强制类型,Coerced Types) |
| 440 | + B. 转换类型(强制类型,Coerced Types) |
441 | 441 |
|
442 | 442 | 考虑下面这个的含义...
|
443 | 443 |
|
|
461 | 461 | // "number"
|
462 | 462 | ...
|
463 | 463 |
|
464 |
| - // 在后续的代码中,你需要更新 `foo` |
465 |
| - // 赋予在 input 元素中得到的新值 |
| 464 | + // 在后续的代码中,你需要更新 `foo`,赋予在 input 元素中得到的新值 |
466 | 465 |
|
467 | 466 | foo = document.getElementById("foo-input").value;
|
468 | 467 |
|
|
585 | 584 |
|
586 | 585 | // 值得注意的是上述都是 "不必要的聪明"
|
587 | 586 | // 采用明确的方案来比较返回的值
|
588 |
| - // indexOf, like: |
| 587 | + // 如 indexOf: |
589 | 588 |
|
590 | 589 | if ( array.indexOf( "a" ) >= 0 ) {
|
591 | 590 | // ...
|
|
611 | 610 | // 结果都是 2
|
612 | 611 |
|
613 | 612 |
|
614 |
| - // 时间牢记心底, 负值将被区别对待... |
| 613 | + // 时刻牢记心底, 负值将被区别对待... |
615 | 614 |
|
616 | 615 | var neg = -2.5;
|
617 | 616 |
|
|
693 | 692 | // 相对于使用这个:
|
694 | 693 | if ( foo === null || foo === undefined ) ...
|
695 | 694 |
|
696 |
| - // ...享受 == 类型强制转换,像这样: |
| 695 | + // ...享受 == 类型强制转换的好处,像这样: |
697 | 696 | if ( foo == null ) ...
|
698 | 697 |
|
699 | 698 | // 谨记,使用 == 将会令 `null` 匹配 `null` 和 `undefined`
|
700 | 699 | // 但不是 `false`,"" 或者 0
|
701 | 700 | null == undefined
|
702 | 701 |
|
703 | 702 | ```
|
704 |
| - 总是判断最好、最准备的值,上述是指南而非教条。 |
| 703 | + 总是判断最好、最精确的值,上述是指南而非教条。 |
705 | 704 |
|
706 | 705 | ```javascript
|
707 | 706 |
|
|
710 | 709 |
|
711 | 710 | // 首次 `===`,`==` 次之 (除非需要松散类型的对比)
|
712 | 711 |
|
713 |
| - // === 总不做类型转换,这意味着: |
| 712 | + // `===` 总不做类型转换,这意味着: |
714 | 713 |
|
715 | 714 | "1" === 1;
|
716 | 715 | // false
|
717 | 716 |
|
718 |
| - // == 会转换类型,这意味着: |
| 717 | + // `==` 会转换类型,这意味着: |
719 | 718 |
|
720 | 719 | "1" == 1;
|
721 | 720 | // true
|
|
820 | 819 | 6. <a name="naming">命名</a>
|
821 | 820 |
|
822 | 821 |
|
823 |
| - |
824 | 822 | A. 你并不是一个人肉 编译器/压缩器,所以尝试去变身为其一。
|
825 | 823 |
|
826 | 824 | 下面的代码是一个极糟命名的典范:
|
|
880 | 878 | // 6.A.3.3
|
881 | 879 | // 命名函数、对象、实例,等
|
882 | 880 |
|
883 |
| - 驼峰; function 和 var 声明 |
| 881 | + camlCase; function 和 var 声明 |
884 | 882 |
|
885 | 883 |
|
886 | 884 | // 6.A.3.4
|
|
909 | 907 |
|
910 | 908 | B. 面对 `this`
|
911 | 909 |
|
912 |
| - 除使用众所周知的 `call` 和 `apply` 外,总是优先选择 `.bind( this )` 或者一个功能物价物,创建 `BoundFunction` 声明供后续调用。仅当没有更好的选择时才使用别名。 |
| 910 | + 除使用众所周知的 `call` 和 `apply` 外,总是优先选择 `.bind( this )` 或者一个功能上等价于它的。创建 `BoundFunction` 声明供后续调用,当没有更好的选择时才使用别名。 |
913 | 911 |
|
914 | 912 | ```javascript
|
915 | 913 |
|
|
1030 | 1028 |
|
1031 | 1029 | C. 使用 `thisArg`
|
1032 | 1030 |
|
1033 |
| - 好几个 ES 5.1 原型中的方法都内置了一个特殊的 `thisArg` 标记,尽可能多地使用它 |
| 1031 | + 好几个 ES 5.1 中的原型的方法都内置了一个特殊的 `thisArg` 标记,尽可能多地使用它 |
1034 | 1032 |
|
1035 | 1033 | ```javascript
|
1036 | 1034 |
|
|
1060 | 1058 |
|
1061 | 1059 | 7. <a name="misc">Misc</a>
|
1062 | 1060 |
|
1063 |
| - 这个部分将要说明的想法和理念都并非教条。相反更鼓励对现存实践保持好奇,以尝试提供完全一般 JavaScript 编程任务的更好方案。 |
| 1061 | + 这个部分将要说明的想法和理念都并非教条。相反更鼓励对现存实践保持好奇,以尝试提供完成一般 JavaScript 编程任务的更好方案。 |
1064 | 1062 |
|
1065 |
| - A. 避免使用 `switch`,现代方法跟踪(method tracing)将会把把带有 switch 表达式的函数列为黑名单。 |
| 1063 | + A. 避免使用 `switch`,现代方法跟踪(method tracing)将会把带有 switch 表达式的函数列为黑名单。 |
1066 | 1064 |
|
1067 | 1065 | 似乎在最新版本的 Firefox 和 Chrome 都对 `switch` 语句有重大改进。http://jsperf.com/switch-vs-object-literal-vs-module
|
1068 | 1066 |
|
|
1095 | 1093 | // 返回值仅作说明用
|
1096 | 1094 | cases = {
|
1097 | 1095 | alpha: function() {
|
1098 |
| - // statements |
1099 |
| - // a return |
| 1096 | + // 语句 |
| 1097 | + // 一个返回值 |
1100 | 1098 | return [ "Alpha", arguments.length ];
|
1101 | 1099 | },
|
1102 | 1100 | beta: function() {
|
1103 |
| - // statements |
1104 |
| - // a return |
| 1101 | + // 语句 |
| 1102 | + // 一个返回值 |
1105 | 1103 | return [ "Beta", arguments.length ];
|
1106 | 1104 | },
|
1107 | 1105 | _default: function() {
|
1108 |
| - // statements |
1109 |
| - // a return |
| 1106 | + // 语句 |
| 1107 | + // 一个返回值 |
1110 | 1108 | return [ "Default", arguments.length ];
|
1111 | 1109 | }
|
1112 | 1110 | };
|
|
1219 | 1217 | * 单行注释放于代码上方为首选
|
1220 | 1218 | * 多行也可以
|
1221 | 1219 | * 行末注释应被避免!
|
1222 |
| - * JSDoc 的方式也不划,但需要比较多的时间 |
| 1220 | + * JSDoc 的方式也不错,但需要比较多的时间 |
1223 | 1221 |
|
1224 | 1222 |
|
1225 | 1223 | 10. <a name="language">单用一门语言</a>
|
|
0 commit comments