JavaScript編碼風格指南(中文版)

前言：

程序語言的編碼風格對於一個長期維護的軟件非常重要，特別是在團隊協作中。如果一個團隊使用統一規范的編碼分風格，可以提高團隊的協作水平和工作效率。編程風格指南的核心是基本的格式化規則，這些規則決定了如何編寫高水准的代碼。本指南來自於《編寫可維護的JavaScript》這本書，基於"Java語言編碼規范"和Crockford的JavaScript編程規范，還有Nicbolas的一些個人經驗和喜好。寫作本文旨在加深自己印象，也為了更多人的了解到JS編碼風格，提高自己的編碼質量。想了解更多的內容請閱讀《編寫可維護的JavaScript》。

1.縮進

每一行的層級由4個空格組成，避免使用Tab進行縮進。

// 好的寫法
if (true) {
    doSomeThing();
}

2.行的長度

每行長度不應超過80個字符。如果一行超過80個字符，應當在一個運算符后換行。下一行應當增加兩級縮進（8個字符）。

// 好的寫法
doSomeThing(argument1, argument2, aegument3, argument4,
        argument5);

// 不好的寫法：第二行只有4個空格的縮進
doSomeThing(argument1, argument2, aegument3, argument4,
    argument5);

3.原始值

字符串應當始終使用雙引號且保持一行，避免在字符串中使用斜線另起一行。

數字應當使用十進制整數，科學計算法表示整數，十六進制整數，或者十進制浮點小數，小數前后應當至少保留一位數字。避免使用八進制直接量。

特殊值null除了下述情況下應當避免使用。

• 用來初始化一個變量，這個變量可能被賦值為一個對象。
• 用來和一個已經初始化的變量比較，這個變量可以是也可以不是一個對象。
• 當函數的參數期望是對象時，被用作參數傳入。
• 當函數的返回值期望是對象時，被用作返回值傳出。

避免使用特殊值undefined。判斷一個變量是否定義應當使用typeof操作符。

4.運算符間距

二元預算符前后必須使用一個空格來保持表達式的整潔。操作符包括賦值運算符和邏輯運算符。

// 好的寫法
for (var i = 0; i < count; i++) {
    process(i);
}

// 不好的寫法：丟失了空格
for (var i=0; i<count; i++) {
    process(i);
}

5.括號間距

當使用括號時，緊接左括號之后和緊接右括號之前不應該有空格。

// 好的寫法
for (var i = 0; i < count; i++) {
    process(i);
}
 
// 不好的寫法：參數兩邊有額外的空格
for (var i = 0; i < count; i++) {
    process( i );
}

6.對象直接量

對象直接量應當有如下格式。

• 起始左花括號應當同表達式保持同一行。
• 每個屬性的名值對應當保持一個縮進，第一個屬性應當在左花括號后另起一行。
• 每個屬性的名值對應當使用不含引號的屬性名，其后緊跟一個冒號（之前不舍空格），其后是值。
• 倘若屬性值是函數類型，函數體應當在屬性名之下另起一行，而且其前后均應保留一個空行。
• 一組相關的屬性前后可以插入空行以提升代碼的可讀性。
• 結束的右花括號應當獨占一行。

// 好的寫法
var object = {

    key1: value1,
    key2: value2,

    func: function() {
    // doSomeThing
    },

    key3: value3
};

// 不好的寫法：不恰當的縮進
var object = {
        key1: value1,
        key2: value2
    };

// 不好的寫法：函數體周圍缺少空行
var object = {

    key1: value1,
    key2: value2,
    func: function() {
    // doSomeThing
    },
    key3: value3
};

當對象字面量作為函數參數時，如果值是變量，起始花括號應當同函數名在同一行。所有其余先前列出的規則同樣適用。

// 好的寫法
doSomeThing({
    key1: value1,
    key2: value2
});
// 不好的寫法：所有代碼在一行上
doSomeThing({ key1: value1, key2: value2 });

7.注釋

使用簡潔明了注釋有助於他人理解你的代碼。如下情況應當使用注釋。

• 代碼晦澀難懂。
• 可能被誤認為錯誤的代碼。
• 必要但不明顯的針對特定瀏覽器的代碼。
• 對於對象、方法或者屬性，生成文檔是有必要的（使用恰當的文檔注釋）。

單行注釋

單行注釋應當用來說明一行代碼或者一組相關的代碼。單行注釋可能有三種使用方式。

• 獨占一行的注釋，用來解釋下一行代碼。
• 在代碼行的尾部的注釋，用來解釋它之前的代碼。
• 多行，用來注釋掉一個代碼塊。

// 好的寫法
if (condition) {

    // 如果代碼執行到這里，則表明通過了所有安全檢查
    allowed();
}

// 不好的寫法：注釋之前沒有空行
if (condition) {
    // 如果代碼執行到這里，則表明通過了所有安全檢查
    allowed();
}

// 不好的寫法：錯誤的縮進
if (condition) {

// 如果代碼執行到這里，則表明通過了所有安全檢查
    allowed();
}

// 不好的寫法：應當使用多行注釋
// 這段代碼進行**判斷
// 然后執行
if (condition) {

    // 如果代碼執行到這里，則表明通過了所有安全檢查
    allowed();
}

// 好的寫法：在行尾注釋時，代碼結尾和注釋間應保留一個空格
if (condition) {

    // 如果代碼執行到這里，則表明通過了所有安全檢查
    allowed(); // 執行**函數
}

// 不好的寫法：代碼和注釋間沒有足夠的空格
if (condition) {

    // 如果代碼執行到這里，則表明通過了所有安全檢查
    allowed();// 執行**函數
}

// 好的寫法：在注釋掉一個代碼塊時，應聯系使用單行注釋，多行注釋不應當使用在此種情況下。
// if (condition) {
//     allowed();//執行**函數
// }

多行注釋

多行注釋應當在代碼需要更多文字去解釋的時候使用。每個多行注釋都至少有如下三行：

1. 首行僅僅包括/*注釋開始。該行不應當有其他文字。
2. 接下來的行以*開頭並保持左對齊。這些可以有文字描述。
3. 最后一行以*/開頭並同先前行保持對齊。也不應有其他文字。

多行注釋的首行應當保持同它描述代碼的相同層次的縮進。后續的每行應當有同樣層次的縮進並附加一個空格（為了適當保持*字符的對齊）。每一個多行代碼之前應當預留一個空行。

// 好的寫法、
if (condition) {

    /*
    * 如果代碼執行到這里
    * 說明通過了所有的安全檢測
    */
    allowed();
}

注釋聲明

注釋有時候也可以用來給一段代碼聲明額外的信息。這些聲明的格式以單個單詞打頭並緊跟一個冒號。可以使用的聲明如下。

TODO：說明代碼還未完成。應當包含下一步要做的事情。

HACK：表明代碼實現走了一個捷徑。應當包含為何使用hack的原因。這也可能表明該問題可能會有更好的解決辦法。

XXX：說明代碼是有問題的並應當盡快修復。

FIXME：說明代碼是有問題的並應盡快修復。重要性略次於XXX。

REVIEW：說明代碼在任何可能的改動都需要評審。

這些聲明可能在一行或者多行注釋中使用，並且應當遵循同一般注釋類型相同的格式規則。

8.命名

變量和函數在命名時應當小心。命名應緊限於數字字母字符，某些情況下可以使用下划線(_)。最好不要在任何命名中使用美元符號($)或者反斜杠(\)。

變量命名應當采用駝峰命名格式，首字母小寫，每個單詞首字母大寫。變量名的第一個單詞應當是一個名詞(而非動詞)以避免同函數混淆。不要在變量名中使用下划線。

// 好的寫法
var accountNumber = "test001";
 
// 不好的寫法：大寫字母開頭
var AccountNumber = "test001";

// 不好的寫法：動詞開頭
var getAccountNumber = "test001";

// 不好的寫法：使用下划線
var account_number = "test001";

函數名也應當采用駝峰命名格式。函數名的第一個單詞應當是動詞（而非名詞）來避免同變量混淆。函數名中最好不要使用下划線。

// 好的寫法
function doSomething() {
    // code
}

// 不好的寫法：大寫字母開頭
function DoSomething() {
    // code
}

// 不好的寫法：名詞開頭
function something() {
    // code
}

// 不好的寫法：使用下划線
function do_something() {
    // code
}

構造函數--通過new運算符創建新對象的函數--也應當以駝峰格式命名並且首字符大寫。構造函數名稱應當以非動詞開頭，因為new代表着創建一個對象實例的操作。

// 好的寫法
function MyObject() {
    // code
}

// 不好的寫法：小寫字母開頭
function myObject() {
    // code
}

// 不好的寫法：使用下划線
function my_object() {
    // code
}

// 不好的寫法：動詞開頭
function getMyObject() {
    // code
}

常量（值不會被改變的變量）的命名應當是所有大寫字母，不同單詞之間單個下划線隔開。

// 好的寫法
var TOTAL_COUNT = 10;

// 不好的寫法：駝峰形式
var totalCount = 10;

// 不好的寫法：混合形式
var total_COUNT = 10;

對象的屬性同變量的命名規則相同。對象的方法同函數的命名規則相同。如果屬性或者方法是私有的，應當在之前加上一個下划線。

// 好的寫法
var object = {
    _count: 10,4 
    _getCount: function() {
        return this._count;
    }
}

9.變量與函數聲明

變量聲明

所有的變量在使用前都應當事先定義。變量定義應當放在函數開頭，使用一個var表達式每行一個變量。除了首行，所有行都應當多一層縮進以使變量名能夠垂直方向對齊。變量定義時應當初始化，並且賦值操作符應當保持一致的縮進。初始化的變量應當在未初始化變量之前。

// 好的寫法
var count = 10,
    name = "jeri",
    found = false,
    empty;

函數聲明

函數應當在使用前提前定義。一個不是作為方法的函數（也就是說沒有作為一個對象的屬性）應當使用函數定義的格式（不是函數表達式和Function構造器格式）。函數名和開始圓括號之間不應當有空格。結束的圓括號和右邊的花括號之間應當留一個空格。右側的花括號應當同function關鍵字保持同一行。開始和結束括號之間不應該有空格。參數名之間應當在逗號之后保留一個空格。函數體應當保持一級縮進。

// 好的寫法
function outer() {
    var count = 10,
        name = "jeri",
        found = false,
        empty;
    function inner() {
        // code
    }
    // 調用inner()的代碼
}

匿名函數可能作為方法賦值給對象，或者作為其他函數的參數。function關鍵字同開始括號之間不應有空格。

// 好的寫法
object.method = function() {
    // code
};

// 不好的寫法：不正確的空格
object.method = function () {
    // code
};

立即被調用的函數應當在函數調用的外層用園括號包裹。

// 好的方法
var value = (function() {

    // 函數體

    return {
        message:"hi"
    }
}());

嚴格模式

嚴格模式應當僅限在函數內部使用，千萬不要在全局使用。

// 不好的寫法：全局使用嚴格模式
"use strict";

function doSomething() {
    // code
}
 
// 好的寫法
function doSomething() {
    "use strict";
 
    // code
}

10.運算符

賦值

給變量賦值時，如果右側是含有比較語句的表達式，需要用圓括號包裹。

// 好的寫法
var flag = (i < count);

// 不好的寫法：遺漏圓括號
var flag = i < count;

等號運算符

使用===（嚴格相等）和!==（嚴格不相等）代替==（相等）和!=（不等）來避免弱類型轉換錯誤。

// 好的寫法
var same = (a === b);

// 好的寫法
var same = (a == b);

三元操作符

三元運算符應當僅僅用在條件賦值語句中，而不要作為if語句的替代品。

// 好的寫法
var value = condition ? value1 : value2;

// 不好的寫法：沒有賦值，應當使用if表達式
condition ? doSomething() : doSomethingElse;

11.語句

簡單語句

每一行最多只包含一條語句。所有簡單的語句都應該以分號(;)結束。

// 好的寫法
count++;
a = b;

// 不好的寫法：多個表達式寫在一行
count++; a = b;

返回語句

返回語句當返回一個值的時候不應當使用圓括號包裹，除非在某些情況下這么做可以讓返回值更容易理解。例如：

return;

return collection.size();

return (size > 0 ? size : defaultSize);

復合語句

復合語句是大括號括起來的語句列表。

• 括起來的語句應當較復合語句多縮進一個層級。
• 開始的大括號應當在復合語句所在行的末尾；結束的大括號應當獨占一行且同復合語句的開始保持同樣的縮進。
• 當語句是控制結構的一部分時，諸如if或者for語句，所有語句都需要用大括號括起來，也包括單個語句。這個約定使得我們更方便地添加語句而不用擔心忘記加括號而引起bug。
• 像if一樣的語句開始的關鍵詞，其后應該緊跟一個空格，起始大括號應當在空格之后。

if 語句

if 語句應當是下面的格式。

if (condition) {
    statements
}

if (condition) {
    statements
} else {
    statements
}

if (condition) {
    statements
} else if (condition) {
    statements
} else {
    statements
}

絕不允許在if語句中省略花括號。

// 好的寫法
if (condition) {
    doSomething();
}

// 不好的寫法：不恰當的空格
if (condition){
    doSomething();
}

// 不好的寫法：所有代碼都在一行
if (condition) { doSomething(); }

// 不好的寫法：所有代碼都在一行且沒有花括號
if (condition) doSomething();

for 語句

for類型的語句應當是下面的格式。

for (initialization; condition; update) {
    statements
}

for (variable in object) {
    statements
}

for語句的初始化部分不應當有變量聲明。

// 好的方法
var i,
    len;

for (i=0, len=0; i < len; i++) {
    // code
}

// 不好的寫法：初始化時候聲明變量
for (var i=0, len=0; i < len; i++) {
    // code
}

// 不好的寫法：初始化時候聲明變量
for (var prop in object) {
    // code
}

當使用for-in語句時，記得使用hasOwnProperty()進行雙重檢查來過濾對象的成員。

while 語句

while 類的語句應當是下面的格式。

while (condition) {
    statements
}

do 語句

do 類的語句應當是下面的格式。

do {
    statements
} while (condition);

switch 語句

switch 類的語句應當是如下格式。

switch (expression) {
    case expression:
        statements

    default:
        statements
}

switch下的第一個case都應當保持一個縮進。除第一個之外包括default在內的每一個case都應當在之前保持一個空行。

每一組語句（除了default）都應當以break、return、throw結尾，或者用一行注釋表示跳過。

// 好的寫法
switch (value) {
    case 1:
        /* falls through */

    case 2:
        doSomething();
        break;

    case 3:
        return true;

    default:
        throw new Error("Some error");
}

如果一個switch語句不包含default情況，應當用一行注釋代替。

// 好的寫法
switch (value) {
    case 1:
        /* falls through */

    case 2:
        doSomething();
        break;

    case 3:
        return true;

    default:
        // 沒有default
}

try 語句

try類的語句應當格式如下。

try {
    statements
} catch (variable) {
    statements
}

try {
    statements
} catch (variable) {
    statements
} finally {
    statements
}

12.留白

在邏輯相關的代碼之間添加空行代碼可以提高代碼的可讀性。

兩行空行僅限於在如下情況下使用：

• 在不同的源代碼文件之間。
• 在類和接口定義之間。

單行空行僅限在如下情況中使用。

• 方法之間。
• 方法中局部變量和第一行語句之間。
• 多行或者單行注釋之前。
• 方法中邏輯代碼塊之間以提升代碼的可讀性。

空格應當在如下的情況下使用。

• 關鍵詞后跟括號的情況應當用空格隔開。
• 參數列表中逗號之后應當保留一個空格。
• 所有的除了點(.)之外的二元運算符，其操作數都應當用空格隔開。單目運算符的操作數之間不應該用空白隔開，例如一元減號，遞增(++)，遞減(--)。
• for 語句的表達式之間應當用空格隔開。

13.需要避免的 

• 切勿使用像String一類的原始包裝類型創建新的對象。
• 避免使用eval()。
• 避免使用with語句。該語句在嚴格模式中不復存在，可能在未來的ECMAScript標准中也將去除。

寫在最后

　　上述指南並不是在開發過程中必須完全遵守的，我們可以只汲取其中的一部分來改善自己的編碼風格，讓自己的代碼易讀、可維護。關於編碼風格，每個團隊都有自己的特色，只要保持團隊一致性，可以高效的開發就OK了。有些規則也並不是我們必須一成不變地遵守的，比如在縮進方面，我們使用Tab鍵很多時候更加地便捷，但是我們不能保證在任何環境下Tab都代表4個空格，為了在縮進方面保持一致性，如果使用Tab鍵那么在整個過程中都要使用；還有關於""和‘’的使用，我們也不必都使用""，使用''也是可以的，只要保持一致的風格就可以了。還有很多其他類似的風格問題，全憑個人選擇。

　　沒有絕對的准則，只有適不適合。