diff --git a/manual/zh-TW/coding-standards/chapters/javascript.md b/manual/zh-TW/coding-standards/chapters/javascript.md index b27fde09..4e1d427b 100644 --- a/manual/zh-TW/coding-standards/chapters/javascript.md +++ b/manual/zh-TW/coding-standards/chapters/javascript.md @@ -1,45 +1,45 @@ ## JavaScript -### Contents - -1. [Naming Conventions](#naming-conventions) - - [Variables](#naming-conventions-variables) - - [Functions](#naming-conventions-functions) - - [Reserved Words](#naming-conventions-reserved) -2. [Syntax Style](#syntax-style) - - [Indentation](#syntax-indentation) - - [Spacing](#syntax-spacing) - - [Commas](#syntax-commas) - - [Semicolons](#syntax-semicolons) - - [Quotes](#syntax-quotes) -3. [Types](#types) -4. [Functions](#functions) -5. [Conditional Statements](#conditional-statements) -6. [Blocks & Multi-line Statements](#blocks) -7. [Comments](#comments) +### 本文 + +1. [命名準則](#naming-conventions) + - [變數](#naming-conventions-variables) + - [函式](#naming-conventions-functions) + - [保留字元](#naming-conventions-reserved) +2. [語法](#syntax-style) + - [縮排](#syntax-indentation) + - [空白](#syntax-spacing) + - [逗號](#syntax-commas) + - [分號](#syntax-semicolons) + - [引號](#syntax-quotes) +3. [變數類型](#types) +4. [函式](#functions) +5. [條件式](#conditional-statements) +6. [程式區塊 (單行與多行)](#blocks) +7. [註解](#comments) -## Naming Conventions +## 命名準則 -Use descriptive words or terse phrases for names. +**變數名稱應該描述其變數意義** -Variables and Functions should be camel case, starting with a lowercase letter: `likeThis` +變數與函式應以駝峰式命名,並以小寫英文字母開頭:`likeThis` -### Variables +### 變數 -**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`) -### Functions +### 函式 -**Use names that describe what the function does:** +**函數名稱應該描述該函數之功能意義** ``` function getSomeData() { @@ -47,50 +47,50 @@ function getSomeData() { } ``` -### Reserved Words +### 保留字元 -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) --- -## Syntax Style +## 語法 -### Indentation -- Don't mix tabs and spaces. -- Tabs, 4 spaces +### 縮排 +- 請勿混用 tab 與 spaces +- Tab 等同 4 個 spaces -### Spacing -- 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. -- 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. -- The ? and : in a ternary conditional must have space on both sides. -- No filler spaces in empty constructs (e.g., {}, [], fn()) -- New line at the end of each file. +### 空白 +- 行末與空行不能有空白字元 +- 一元運算子(例如:!, ++)前後不可包含空白字元 +- 任何 , 以及 ; 不可前綴空白字元 (例如:[ 'name', 'age' ]) +- 以分號(;)結束程式區塊時,分號(;)必須放在行末 +- 在物件內定義屬性時使用的冒號(:)不可前綴空白字元 (例如:{"name": "jack"}) +- 三元運算子中的 ? 以及 : 前後都必須包含空白字元 +- 空白宣告中不需要包含空白字元 (例如:{}, [], fn()) +- 檔案末尾需有一空行 -**Array:** +**陣列:** ``` var array = [ 'foo', 'bar' ]; ``` -**Function call:** +**函式呼叫:** ``` foo( arg ); ``` -**Function call with multiple arguments:** +**多變數的函式呼叫:** ``` foo( 'string', object ); ``` -**Conditional Statements** +**條件式** ``` if ( condition ) { @@ -113,11 +113,11 @@ for ( prop in object ) { ``` -#### Exceptions +#### 空白字元例外狀況 -**First or only argument is an object, array or callback function.** +**函式的第一個變數是物件、陣列或是 callback 函式時:** -**No space before the first argument:** +**第一個變數不需前綴空白字元** ``` foo({ @@ -132,9 +132,9 @@ 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. +**最後一個變數不需後綴空白字元:** ``` foo( data, function() { @@ -143,37 +143,38 @@ foo( data, function() { ``` -### Commas +### 逗號 -**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:** +**正確:** ``` array = [ 'foo', 'bar' ]; ``` -### Semicolons +### 分號 -Use them where expected. +在預期狀況下使用 -Semicolons should be included at the end of function expressions, but not at the end of function declarations. +以變數宣告函式時必須以分號結尾,單純宣告函式時則不需要 -**Function Expression:** +**以變數宣告函式:** ``` var foo = function() { @@ -181,7 +182,7 @@ var foo = function() { }; ``` -**Function Declaration:** +**宣告函式:** ``` function foo() { @@ -190,25 +191,24 @@ function foo() { ``` -### Quotes - -Use ' instead of " +### 引號 +使用單引號(')而非雙引號(") --- -## Variables +## 變數 -### Avoid Global Variables +### 避免宣告全域變數 -**No:** +**錯誤:** ``` foo = 'bar'; ``` -**No: implied global** +**錯誤: 在函式範疇但仍為全域宣告** ``` function() { @@ -216,17 +216,17 @@ function() { } ``` -**Yes:** +**正確:** ``` var foo = 'bar'; ``` -### Multiple Variable Declarations +### 多個變數宣告 -Use one `var` declaration and separate each variable on a newline ending with a comma. +只使用一個 `var` 作為宣告,一行只能存在一個變數並在行末以逗號作為結束 -**No:** +**錯誤:** ``` var foo = 'bar'; @@ -234,22 +234,22 @@ var bar = 'baz'; var baz = 'qux'; ``` -**Yes:** +**正確:** ``` var foo = 'bar', bar = 'baz', - baz = 'qux'; + baz = 'qux'; ``` -## Types +## 變數類別 -### String +### 字串 -- Concatenate long strings. -- Place space before closing quote at the end of each string. -- Concatenation operator at the end of each subsequent string. +- 過長字串應以串接形式宣告 (使用 +) +- 有需要隔斷單字的空白,需要放在每一行字串的尾部,而非下一行字串的開頭 +- 串接運算子應放在每個字串片段的結尾 ``` var longString = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. ' + @@ -260,57 +260,58 @@ var longString = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. ' + 'cursus mauris.'; ``` -### Number +### 數字 -Use `parseInt()` or `parseFloat()` instead of unary plus, for readability. +為了閱讀性考量,應使用parseInt() 或 parseFloat() 將變數轉為數字,而非用一元運算子 + -**No:** +**錯誤:** ``` var count = +document.getElementById('inputId').value; ``` -**Yes:** +**正確:** ``` var count = parseInt(document.getElementById('inputId').value); ``` -### Type Checks +### 變數類型檢查 -- String: `typeof object === 'string'` -- Number: `typeof object === 'number'` -- Boolean: `typeof object === 'boolean'` -- Object: `typeof object === 'object'` -- Plain Object: `jQuery.isPlainObject( object )` -- Function: `jQuery.isFunction( object )` -- Array: `jQuery.isArray( object )` -- Element: `object.nodeType` +- 字串: `typeof object === 'string'` +- 數字: `typeof object === 'number'` +- 布林: `typeof object === 'boolean'` +- 物件: `typeof object === 'object'` +- 空白物件: `jQuery.isPlainObject( object )` +- 函式: `jQuery.isFunction( object )` +- 陣列: `jQuery.isArray( object )` +- HTML元素: `object.nodeType` - null: `object === null` - null or undefined: `object == null` **Undefined:** -- Global Variables: `typeof variable === 'undefined'` -- Local Variables: `variable === undefined` -- Properties: `object.prop === undefined` +- 全域變數: `typeof variable === 'undefined'` +- 區域變數: `variable === 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 = { @@ -320,22 +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()`,來增加新的元素 ``` var myArr = []; @@ -343,9 +345,9 @@ myArr.push('foo'); ``` -## Functions +## 函式 -### Chaining Method Calls +### 鏈狀呼叫 ``` $('.someElement') @@ -355,18 +357,18 @@ $('.someElement') ``` -## Conditional Statements +## 條件式 -Use ternary syntax if: +在下列情況使用三元運算子: -- One condition -- Result of either evaluation is one operation. +- 只有一個條件 +- 程式區塊內只包含一個操作時 ``` joomlaRocks ? 'This is true' : 'else it is false'; ``` -Otherwise, use standard syntax: +否則就使用標準語法 ``` if ( condition ) { @@ -376,7 +378,7 @@ if ( condition ) { } ``` -**Cache length in variable for performance:** +**將變數長度做快取以提升效能:** ``` var i, @@ -387,7 +389,7 @@ for ( i = 0; i < j; i++ ) { } ``` -**With more than one condition:** +**一組以上的條件時:** ``` if ( condition && @@ -399,9 +401,9 @@ if ( condition && } ``` -### Equality +### 等式判斷 -Use strict equality operator === so that type is considered in comparison. Using == can produce false positives. +使用強型別等號運算子 === 判斷,這會將變數類型一同比較。使用 == 可能會造成以假為真 ``` @@ -415,17 +417,17 @@ 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:** +**多行敘述的區塊:** ``` if ( test ) { @@ -435,23 +437,22 @@ if ( test ) { ``` -## Comments +## 註解 -**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 個星號後綴一個空白 ``` /*