前言
編碼風格這件事,平時看不出差別,一旦進入長期維護或團隊協作就會被放大。同一個團隊若共用一套規則,溝通成本會明显下降,交付品質也更穩定。風格指南的核心其實很樸素——就是一些基本的格式化規則,但它們決定了程式碼讀起來順不順。
這份指南整理自《編寫可維護的 JavaScript》,並參考 Java 語言編碼規範、Crockford 的 JavaScript 編程規範,以及 Nicolas 的一些個人偏好。
每一層縮進用 4 個空格,不要拿 Tab 來縮進。
// 好的寫法
if (true) {
doSomething();
}一行別超過 80 個字元。真的超了,就在運算子後面換行,下一行多縮進兩層(8 個字元)。
// 好的寫法
doSomething(argument1, argument2, argument3, argument4,
argument5);字串一律用雙引號並保持在同一行,不要靠斜線硬拆。
數字優先使用十進位整數;若用科學記號、十六進位或浮點數,小數點前後至少要留一位數字。八進位字面量請避開。
特殊值 null 只在這幾種情況使用:
• 初始化一個稍後可能被指派為物件的變數。
• 與一個已初始化的變數做比較。
• 函數參數預期是物件時作為傳入值。
• 函數返回值預期是物件時作為傳出值。
至於 undefined,請避免使用。要判斷變數有沒有被定義,用 typeof 運算子。
二元運算子前後各留一個空格,包含指派與邏輯運算子。
// 好的寫法
for (var i = 0; i < count; i++) {
process(i);
}
// 不好的寫法:空格不見了
for (var i=0; i<count; i++) {
process(i);
}左括號之後、右括號之前都不要有空格。
// 不好的寫法:參數兩側多了空格
for (var i = 0; i < count; i++) {
process( i );
}格式要點如下:
• 起始左花括號與運算式同行。
• 每組名值對縮進一層,第一個屬性從左花括號後換行。
• 屬性名不加引號,緊接冒號(冒號前不留空格),再寫值。
• 若屬性值是函數,函數體從屬性名另起一行,且前後各留一個空行。
• 相關屬性之間可插入空行提升可讀性。
• 結束的右花括號獨占一行。
// 好的寫法
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
});好的註解能替別人省下大量時間。以下情況值得寫註解:程式碼本身晦澀難懂、容易被誤認為是錯誤、屬於必要但不顯眼的瀏覽器相容處理,以及需要生成文件(此時請用正式的文件註解格式)。
單行註解
單行註解有三種用法:獨占一行解釋下一段程式碼、掛在程式碼行尾解釋該行、或連續多行用來註掉一整塊程式碼。
// 好的寫法
if (condition) {
// 執行到這裡,代表已通過所有安全檢查
allowed();
}
// 不好的寫法:註解前沒有空行、縮進錯誤
if (condition) {
// 執行到這裡,代表已通過所有安全檢查
allowed();
}
// 行尾註解時,程式碼與註解之間要留一個空格
if (condition) {
allowed(); // 執行風險操作
}
// 註掉整段程式碼時,請連續使用單行註解
// if (condition) {
// allowed(); // 執行風險操作
// }多行註解
需要更多篇幅解釋時才用多行註解,且每個多行註解至少要有三行:首行只有 /*,中間各行以 * 開頭並靠左對齊,末行以 */ 開頭並與前此行對齊。首行的縮進要與被描述程式碼同層,每個多行註解之前留一個空行。
// 好的寫法
if (condition) {
/*
* 執行到這裡
* 代表通過了所有安全檢測
*/
allowed();
}註解聲明
註解也可以用來標記額外資訊,格式是「單字 + 冒號」:
TODO:程式碼尚未完成,應註明下一步要做什麼。
HACK:這裡走了捷徑,應說明原因,也可能暗示存在更好的解法。
XXX:有問題,需盡快修復。
FIXME:有問題需修復,緊急程度略低於 XXX。
REVIEW:任何改動都需要先經過評審。
命名只使用英數字母,某些情況可用底線,盡量不要出現 $ 或反斜線。
變數採用駝峰式、首字母小寫,且第一個單字應是名詞而非動詞,以免與函數混淆;變數名不用底線。
// 好的寫法 var accountNumber = "test001"; // 不好的寫法:大寫開頭 var AccountNumber = "test001"; // 不好的寫法:動詞開頭 var getAccountNumber = "test001"; // 不好的寫法:使用底線 var account_number = "test001";
函數同樣用駝峰式,但第一個單字應是動詞。
// 好的寫法
function doSomething() {
// code
}
// 不好的寫法:大寫開頭
function DoSomething() { }
// 不好的寫法:名詞開頭
function something() { }
// 不好的寫法:使用底線
function do_something() { }構造函數(搭配 new 建立物件的函數)用駝峰式且首字母大寫,並以非動詞開頭,因為 new 本身就表達了「建立實例」這個動作。
// 好的寫法
function MyObject() {
// code
}
// 不好的寫法:小寫開頭
function myObject() { }
// 不好的寫法:使用底線
function my_object() { }
// 不好的寫法:動詞開頭
function getMyObject() { }常數全部大寫,單字之間用單一底線分隔。
// 好的寫法 var TOTAL_COUNT = 10; // 不好的寫法:駝峰形式 var totalCount = 10; // 不好的寫法:混合形式 var total_COUNT = 10;
物件屬性比照變數規則,方法比照函數規則;私有成員前面加一個底線。
// 好的寫法
var object = {
_count: 10,
_getCount: function () {
return this._count;
}
};所有變數都必須在使用前宣告,且宣告集中在函數開頭,用一個 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
}指派時,若右側是含比較運算的運算式,請用圓括號包起來。
// 好的寫法 var flag = (i < count); // 不好的寫法:漏了括號 var flag = i < count;
等號運算一律使用 === 與 !==,避開 ==/!= 帶來的型別轉換陷阱。
// 好的寫法 var same = (a === b);
三元運算子只用於條件指派,不要拿來取代 if 語句。
// 好的寫法 var value = condition ? value1 : value2; // 不好的寫法:沒有指派,應該改用 if condition ? doSomething() : doSomethingElse();
簡單語句:一行最多一條,且以分號結尾。
// 不好的寫法:兩個運算式擠在一行 count++; a = b;
返回語句:回傳值不加圓括號,除非這樣能讓意圖更清楚。
return; return collection.size(); return (size > 0 ? size : defaultSize);
複合語句:大括號內的內容多縮進一層;起始大括號在該行末尾,結束大括號獨占一行並與起始處同層縮進。只要是控制結構(if、for 等),即使只有一條語句也必須加大括號——這樣之後要補程式碼時,就不必擔心忘記補括號而釀成 bug。關鍵字後緊跟一個空格,起始大括號在空格之後。
if (condition) {
statements
}
if (condition) {
statements
} else {
statements
}
if (condition) {
statements
} else if (condition) {
statements
} else {
statements
}for 與 while、do 的格式:
for (initialization; condition; update) {
statements
}
for (variable in object) {
statements
}
while (condition) {
statements
}
do {
statements
} while (condition);for 的初始化部分不要宣告變數。
// 好的寫法
var i,
len;
for (i = 0, len = 0; i < len; i++) {
// code
}
// 不好的寫法:初始化時宣告變數
for (var i = 0, len = 0; i < len; i++) {
// code
}使用 for-in 時,記得用 hasOwnProperty() 做二次檢查,把原型鏈上的成員濾掉。
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");
}若刻意不寫 default,用一行註解交代。
switch (value) {
case 1:
/* falls through */
case 2:
doSomething();
break;
case 3:
return true;
default:
// 沒有 default
}try 的格式:
try {
statements
} catch (variable) {
statements
}
try {
statements
} catch (variable) {
statements
} finally {
statements
}邏輯相關的程式碼之間加空行,可讀性會明顯提升。
兩行空行只用於:不同原始檔之間、類別與介面定義之間。
單行空行用於:方法之間、方法中區域變數與第一條語行之間、多行或單行註解之前、方法中邏輯區塊之間。
空格的使用時機:關鍵字後接括號時要空格隔開;參數清單中逗號之後留一個空格;除點(.)以外的二元運算子,運算元兩側都要空格;一元運算子(一元負號、++、--)與運算元之間不留空白;for 語句中各段運算式之間用空格隔開。
• 不要用 String 這類原始包裝型別去建立新物件。
• 不要用 eval()。
• 不要用 with 語句——它在嚴格模式下已不存在,未來的 ECMAScript 標準也可能移除。
這份指南並非鐵律。你完全可以只挑其中一部分來改善自己的風格,讓程式碼更易讀、更好維護。每個團隊都有自己的習慣,重點是一致性與開發效率。
有些規則也不必死守。例如縮進,用 Tab 在很多環境下更順手,但前提是無法保證處處都恰好等於 4 個空格;如果決定用 Tab,那麼全程都要用。引號也是同理,用單引號或雙引號都可以,統一就好。
沒有絕對正確的準則,只有適不適合。