DIV CSS 佈局教程網

JavaScript 編碼風格指南:讓程式碼好讀又好維護
編輯:關於JavaScript     

前言

編碼風格這件事,平時看不出差別,一旦進入長期維護或團隊協作就會被放大。同一個團隊若共用一套規則,溝通成本會明显下降,交付品質也更穩定。風格指南的核心其實很樸素——就是一些基本的格式化規則,但它們決定了程式碼讀起來順不順。

這份指南整理自《編寫可維護的 JavaScript》,並參考 Java 語言編碼規範、Crockford 的 JavaScript 編程規範,以及 Nicolas 的一些個人偏好。

1. 縮進

每一層縮進用 4 個空格,不要拿 Tab 來縮進。

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

2. 行長度

一行別超過 80 個字元。真的超了,就在運算子後面換行,下一行多縮進兩層(8 個字元)。

// 好的寫法
doSomething(argument1, argument2, argument3, 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 );
}

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
});

7. 註解

好的註解能替別人省下大量時間。以下情況值得寫註解:程式碼本身晦澀難懂、容易被誤認為是錯誤、屬於必要但不顯眼的瀏覽器相容處理,以及需要生成文件(此時請用正式的文件註解格式)。

單行註解

單行註解有三種用法:獨占一行解釋下一段程式碼、掛在程式碼行尾解釋該行、或連續多行用來註掉一整塊程式碼。

// 好的寫法
if (condition) {

    // 執行到這裡,代表已通過所有安全檢查
    allowed();
}

// 不好的寫法:註解前沒有空行、縮進錯誤
if (condition) {
// 執行到這裡,代表已通過所有安全檢查
        allowed();
}

// 行尾註解時,程式碼與註解之間要留一個空格
if (condition) {
    allowed();  // 執行風險操作
}

// 註掉整段程式碼時,請連續使用單行註解
// if (condition) {
//     allowed();  // 執行風險操作
// }

多行註解

需要更多篇幅解釋時才用多行註解,且每個多行註解至少要有三行:首行只有 /*,中間各行以 * 開頭並靠左對齊,末行以 */ 開頭並與前此行對齊。首行的縮進要與被描述程式碼同層,每個多行註解之前留一個空行。

// 好的寫法
if (condition) {
    /*
     * 執行到這裡
     * 代表通過了所有安全檢測
     */
    allowed();
}

註解聲明

註解也可以用來標記額外資訊,格式是「單字 + 冒號」:

TODO:程式碼尚未完成,應註明下一步要做什麼。
HACK:這裡走了捷徑,應說明原因,也可能暗示存在更好的解法。
XXX:有問題,需盡快修復。
FIXME:有問題需修復,緊急程度略低於 XXX。
REVIEW:任何改動都需要先經過評審。

8. 命名

命名只使用英數字母,某些情況可用底線,盡量不要出現 $ 或反斜線。

變數採用駝峰式、首字母小寫,且第一個單字應是名詞而非動詞,以免與函數混淆;變數名不用底線。

// 好的寫法
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;
    }
};

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);

三元運算子只用於條件指派,不要拿來取代 if 語句。

// 好的寫法
var value = condition ? value1 : value2;
// 不好的寫法:沒有指派,應該改用 if
condition ? doSomething() : doSomethingElse();

11. 語句

簡單語句:一行最多一條,且以分號結尾。

// 不好的寫法:兩個運算式擠在一行
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
}

12. 留白

邏輯相關的程式碼之間加空行,可讀性會明顯提升。

兩行空行只用於:不同原始檔之間、類別與介面定義之間。

單行空行用於:方法之間、方法中區域變數與第一條語行之間、多行或單行註解之前、方法中邏輯區塊之間。

空格的使用時機:關鍵字後接括號時要空格隔開;參數清單中逗號之後留一個空格;除點(.)以外的二元運算子,運算元兩側都要空格;一元運算子(一元負號、++、--)與運算元之間不留空白;for 語句中各段運算式之間用空格隔開。

13. 該避開的東西

• 不要用 String 這類原始包裝型別去建立新物件。
• 不要用 eval()。
• 不要用 with 語句——它在嚴格模式下已不存在,未來的 ECMAScript 標準也可能移除。

寫在最後

這份指南並非鐵律。你完全可以只挑其中一部分來改善自己的風格,讓程式碼更易讀、更好維護。每個團隊都有自己的習慣,重點是一致性與開發效率。

有些規則也不必死守。例如縮進,用 Tab 在很多環境下更順手,但前提是無法保證處處都恰好等於 4 個空格;如果決定用 Tab,那麼全程都要用。引號也是同理,用單引號或雙引號都可以,統一就好。

沒有絕對正確的準則,只有適不適合。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved