前言:
程序語言的編碼風格對於一個長期維護的軟件非常重要,特別是在團隊協作中。如果一個團隊使用統一規范的編碼分風格,可以提高團隊的協作水平和工作效率。編程風格指南的核心是基本的格式化規則,這些規則決定了如何編寫高水准的代碼。本指南來自於《編寫可維護的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鍵那麼在整個過程中都要使用;還有關於""和‘'的使用,我們也不必都使用"",使用''也是可以的,只要保持一致的風格就可以了。還有很多其他類似的風格問題,全憑個人選擇。
沒有絕對的准則,只有適不適合。