From 4ba4cc46647acf687c3f369fbb10b4315323bc48 Mon Sep 17 00:00:00 2001 From: skylying Date: Thu, 25 Sep 2014 13:31:45 +0800 Subject: [PATCH] translation refector --- .../coding-standards/chapters/javascript.md | 154 ++++-------------- 1 file changed, 30 insertions(+), 124 deletions(-) diff --git a/manual/zh-TW/coding-standards/chapters/javascript.md b/manual/zh-TW/coding-standards/chapters/javascript.md index 996f0af7..d8426df6 100644 --- a/manual/zh-TW/coding-standards/chapters/javascript.md +++ b/manual/zh-TW/coding-standards/chapters/javascript.md @@ -21,31 +21,25 @@ ## 命名準則 -Use descriptive words or terse phrases for names. -命名應以具有描述性或簡潔為準則 +**變數名稱應該描述其變數意義** -Variables and Functions should be camel case, starting with a lowercase letter: `likeThis` 變數與函式應以駝峰式命名，並以小寫英文字母開頭：`likeThis` ### 變數 -**Use names that describe what the variable is:** **使用描述變數意義的命名準則** `var element = document.getElementById('elementId');` -**Iterators are the exception** -遞回函式內的變數則不在此限 +**迭代子則不在此限** -Use i for index in a loop (and subsequent letters when necessary for nested iteration). 例如在迴圈中允許使用 `i` 作為索引值 (遇到巢狀結構時使用下一個英文字母：`j`) ### 函式 -**Use names that describe what the function does:** -**使用描述函式功能的命名準則** +**函數名稱應該描述該函數之功能意義** ``` function getSomeData() { @@ -55,8 +49,7 @@ function getSomeData() { ### 保留字元 -Do not use reserved words for anything other than their intended use. The list of: [Reserved Words](http://es5.github.io/#x7.6.1) -非必要狀況下不要使用保留字元作為命名。完整的保留字元列表：[保留字元列表](http://es5.github.io/#x7.6.1) +除非需要用到保留字功能的場合，否則不要在任何地方使用到保留字。完整的保留字元列表：[保留字元列表](http://es5.github.io/#x7.6.1) --- @@ -65,52 +58,38 @@ Do not use reserved words for anything other than their intended use. The list o ### 縮排 -- Don't mix tabs and spaces. -請勿混淆 tab 與 spaces -- Tabs, 4 spaces +請勿混用 tab 與 spaces Tab 等同 4 個 spaces ### 空白 -- No whitespace at the end of line or on blank lines. -行末不可含有空白字元 (空行亦同) -- Unary special-character operators (e.g., !, ++) must not have space next to their operand. -單元運算子(例如：!, ++)前後不可包含空白字元 -- Any , and ; must not have preceding space. -任何 , 以及 ; 不可前綴空白字元 (例如：[ 'name', 'age' ]) -- Any ; used as a statement terminator must be at the end of the line. -以分號(;)結束程式區塊時，分號(;)必須放在行末 -- Any : after a property name in an object definition must not have preceding space. -在物件內定義屬性時使用的冒號(:)不可前綴空白字元 (例如：{"name": "jack"}) -- The ? and : in a ternary conditional must have space on both sides. -三元運算式中的 ? 以及 : 前後都必須包含空白字元 -- No filler spaces in empty constructs (e.g., {}, [], fn()) -空白宣告中不需要包含空白字元 (例如：{}, [], fn()) -- New line at the end of each file. -檔案末尾需有一行空白 - -**Array:** +- 行末與空行不能有空白字元 +- 一元運算子(例如：!, ++)前後不可包含空白字元 +- 任何 , 以及 ; 不可前綴空白字元 (例如：[ 'name', 'age' ]) +- 以分號(;)結束程式區塊時，分號(;)必須放在行末 +- 在物件內定義屬性時使用的冒號(:)不可前綴空白字元 (例如：{"name": "jack"}) +- 三元運算子中的 ? 以及 : 前後都必須包含空白字元 +- 空白宣告中不需要包含空白字元 (例如：{}, [], fn()) +- 檔案末尾需有一空行 + **陣列:** ``` var array = [ 'foo', 'bar' ]; ``` -**Function call:** **函式呼叫:** ``` foo( arg ); ``` -**Function call with multiple arguments:** **多變數的函式呼叫:** ``` foo( 'string', object ); ``` -**Conditional Statements** **條件式** ``` @@ -136,10 +115,8 @@ for ( prop in object ) { #### 空白字元例外狀況 -**First or only argument is an object, array or callback function.** **函式的第一個變數是物件、陣列或是 callback 函式時:** -**No space before the first argument:** **第一個變數不需前綴空白字元** ``` @@ -155,10 +132,8 @@ foo(function() { }, options ); // space after options argument ``` -**Function with a callback, object, or array as the last argument:** **函式的最後一個變數是物件、陣列或是 callback 函式時:** -No space after the last argument. **最後一個變數不需後綴空白字元:** ``` @@ -170,28 +145,22 @@ foo( data, function() { ### 逗號 -**Place commas after:** **下列情形必須後綴逗號:** -- variable declarations - 變數宣告 -- key/value pairs - 索引/值 配對 #### Arrays #### 陣列 -Do not include a trailing comma, this will add 1 to your array's length. 最後一個元素不需後綴逗號，這會造成陣列長度多了 1 -**No:** **錯誤:** ``` array = [ 'foo', 'bar', ]; ``` -**Yes:** **正確:** ``` @@ -201,13 +170,10 @@ array = [ 'foo', 'bar' ]; ### 分號 -Use them where expected. 在預期狀況下使用 -Semicolons should be included at the end of function expressions, but not at the end of function declarations. 以變數宣告函式時必須以分號結尾，單純宣告函式時則不需要 -**Function Expression:** **以變數宣告函式:** ``` @@ -216,7 +182,6 @@ var foo = function() { }; ``` -**Function Declaration:** **宣告函式:** ``` @@ -228,26 +193,21 @@ function foo() { ### 引號 -Use ' instead of " -使用單引號而非雙引號 - +使用單引號(')而非雙引號(") --- ## 變數 -### Avoid Global Variables ### 避免宣告全域變數 -**No:** **錯誤:** ``` foo = 'bar'; ``` -**No: implied global** **錯誤: 在函式範疇但仍為全域宣告** ``` @@ -256,20 +216,16 @@ function() { } ``` -**Yes:** **正確:** ``` var foo = 'bar'; ``` -### Multiple Variable Declarations ### 多個變數宣告 -Use one `var` declaration and separate each variable on a newline ending with a comma. -只使用一個 `var` 作為宣告，其餘變數每個以逗號隔開並換新行 +只使用一個 `var` 作為宣告，一行只能存在一個變數並在行末以逗號作為結束 -**No:** **錯誤:** ``` @@ -278,13 +234,12 @@ var bar = 'baz'; var baz = 'qux'; ``` -**Yes:** **正確:** ``` var foo = 'bar', bar = 'baz', - baz = 'qux'; + baz = 'qux'; ``` @@ -292,11 +247,8 @@ var foo = 'bar', ### 字串 -- Concatenate long strings. - 過長字串應以串接形式宣告 (使用 +) -- Place space before closing quote at the end of each string. -- 結束字串的引號應前綴空白字元 -- Concatenation operator at the end of each subsequent string. +- 有需要隔斷單字的空白，需要放在每一行字串的尾部，而非下一行字串的開頭 - 串接運算子應放在每個字串片段的結尾 ``` @@ -310,75 +262,56 @@ var longString = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. ' + ### 數字 -Use `parseInt()` or `parseFloat()` instead of unary plus, for readability. -為了閱讀性考量，運算為數字的變數時應使用`parseInt()` 或 `parseFloat()`，而非單純的 + +為了閱讀性考量，應使用parseInt() 或 parseFloat() 將變數轉為數字，而非用一元運算子 + -**No:** **錯誤:** ``` var count = +document.getElementById('inputId').value; ``` -**Yes:** **正確:** ``` var count = parseInt(document.getElementById('inputId').value); ``` -### Type Checks ### 變數類型檢查 -- String: `typeof object === 'string'` - 字串: `typeof object === 'string'` -- Number: `typeof object === 'number'` - 數字: `typeof object === 'number'` -- Boolean: `typeof object === 'boolean'` - 布林: `typeof object === 'boolean'` -- Object: `typeof object === 'object'` - 物件: `typeof object === 'object'` -- Plain Object: `jQuery.isPlainObject( object )` - 空白物件: `jQuery.isPlainObject( object )` -- Function: `jQuery.isFunction( object )` - 函式: `jQuery.isFunction( object )` -- Array: `jQuery.isArray( object )` - 陣列: `jQuery.isArray( object )` -- Element: `object.nodeType` - HTML元素: `object.nodeType` - null: `object === null` - null or undefined: `object == null` **Undefined:** -- Global Variables: `typeof variable === 'undefined'` - 全域變數: `typeof variable === 'undefined'` -- Local Variables: `variable === undefined` - 區域變數: `variable === undefined` -- Properties: `object.prop === undefined` - 屬性: `object.prop === undefined` -### Objects ### 物件 -Use the literal, not constructor, syntax. -使用大括號建立物件，而非建構方式 +使用大括號建立物件，而非建構子方式 -**No:** **錯誤:** ``` var myObj = new Object(); ``` -**Yes:** + **正確:** ``` var myObj = {}; ``` -If an object contains more than one key/value pair or an array as a value, each key/value pair should be on its own line. -如果物件包含多組 索引/值，每一組 索引/值 都必須是一個獨立的行 +如果物件包含多組索引/值或陣列，每一組 索引/值 都必須是一個獨立的行 ``` var myObj = { @@ -388,27 +321,23 @@ var myObj = { }; ``` -### Arrays ### 陣列 -Use the literal, not constructor, syntax -使用中括號建立物件，而非建構方式 +使用中括號建立物件，而非建構子方式 -**No:** **錯誤:** ``` var myArr = new Array(); ``` -**Yes:** + **正確:** ``` var myArr = []; ``` -If you don't know array length use push method. This will replace the current array. -陣列長度未知的狀況下使用 `push()`，這會取代現有陣列 +陣列長度未知的狀況下使用 `push()`，來增加新的元素 ``` var myArr = []; @@ -416,11 +345,9 @@ myArr.push('foo'); ``` -## Functions ## 函式 -### Chaining Method Calls -### 呼叫連鎖方法 +### 鏈狀呼叫 ``` $('.someElement') @@ -430,22 +357,17 @@ $('.someElement') ``` -## Conditional Statements ## 條件式 -Use ternary syntax if: -在下列情況使用三元運算式: +在下列情況使用三元運算子: -- One condition - 只有一個條件 -- Result of either evaluation is one operation. -- 看不太懂 by Tim 2014-09-24 +- 程式區塊內只包含一個操作時 ``` joomlaRocks ? 'This is true' : 'else it is false'; ``` -Otherwise, use standard syntax: 否則就使用標準語法 ``` @@ -456,7 +378,6 @@ if ( condition ) { } ``` -**Cache length in variable for performance:** **將變數長度做快取以提升效能:** ``` @@ -468,7 +389,6 @@ for ( i = 0; i < j; i++ ) { } ``` -**With more than one condition:** **一組以上的條件時:** ``` @@ -481,11 +401,9 @@ if ( condition && } ``` -### Equality ### 等式判斷 -Use strict equality operator === so that type is considered in comparison. Using == can produce false positives. -使用最嚴謹的 === 判斷，這會將變數類型一同比較。使用 == 可能會造成以假為真 +使用強型別等號運算子 === 判斷，這會將變數類型一同比較。使用 == 可能會造成以假為真 ``` @@ -499,20 +417,16 @@ Use strict equality operator === so that type is considered in comparison. Using ``` -## Blocks & Multi-line Statements ## 程式區塊 & 多行敘述 -Use curly braces on blocks that have more than one statement. 多行程式敘述時應以大括號區隔範圍 -**Block with one statement:** **單一敘述的區塊:** ``` if ( test ) return false; ``` -**Block with more than one statement:** **多行敘述的區塊:** ``` @@ -525,28 +439,20 @@ if ( test ) { ## 註解 -**Single Line** **單行** -- Place above the code it refers to. - 註解放置在程式碼上方 -- A space between double forward slashes and comment text. - 雙斜線與註解之間應空一格 ``` // I am a single line comment. ``` - -**Multiline** **多行註解** -- Place above the code it refers to. - 多行註解應放置在說明的目標程式碼上方 -- Opening token placed on the line above first comment line, closing placed below last comment line. - 註解起始字元 `/*` 應放在第一行註解上方，註解結束字元 `*/` 應放在最後一行註解下方， -- Each comment line begins with two astericks followed by a space. -- 每一行註解應以 2 個星號與 1 個空白字元開頭 +- 每一行註解應加上 2 個星號後綴一個空白 ``` /*