Gallery

無瑕的程式碼 Clean Code

前言

有意義的命名

常見的命名法

函式

註解

Explore

有意義的命名

1.1 命名須展現意圖

變數、類別、函式的名稱應該要「有意義」，要能夠解決大多數的問題，包括：

為什麼要在這裡出現

要做什麼

該如何使用它

如果一個名稱還需要註解的輔助，那他就不具備展現意圖這個能力。

範例

下方的例子就不是一個好的變數名稱。

int d; // 消逝的天數

如要更好表達其含義，可改成：

int elapsedTimeInDays;

int daysSinceCreaction;

int daysSinceModification;

int fileAgeInDays;

這樣會更能夠展現其意圖，更容易地瞭解和修改程式碼。

⁠

1.2 避免誤導

我們應該要避免使用那些與原意圖違背的字詞，像是：

要表達「一堆帳戶」時，避免使用 accountList 當作變數名稱，除非其變數型態真的是 List（用 accountGroup 會相對較好）

避免使用「小寫 L 」或「大寫 O」當作變數，不然容易跟「1」和「0」搞混

⁠

1.3 產生有意義的區別

1、可以的話，盡可能不要使用「數字序列命名法」（a1 , a2, ... , aN）

他雖然非誤導，但仍屬無效資訊，無法讓人一眼就明白與理解其意圖。

舉例：

/**

* 擇一必填驗證器

* @param a - 第一個表單欄位名稱

* @param b - 第二個表單欄位名稱

* @returns 錯誤代碼或null

static chooseOneRequiredValidator(a: string, b: string) {

return (formGroup: AbstractControl): ValidationErrors | null => {

/** 兩個欄位皆未填 */

if (formGroup.get(a)?.value === '' && formGroup.get(b)?.value === '') {

return { chooseOneRequire: true };

}

return null;

};

}

比起用 a, b 來命名參數，使用 controlNameA 和 controlNameB 來區分會更符合「意圖」。

2、無意義的字詞，也是一種無意義的區別。

productData VS. productInfo

moneyAccount VS. money

theMessage VS. message

⁠

1.4 使用能唸出來的名稱

避免使用自己捏造出來的變數名稱

aaa

genymdhms

pszqint

⁠

1.5 命名規則

類別（class）和物件（Object）

應使用名詞或名詞片語來命名

例如：Customer（顧客）、Account（帳戶）

方法

應使用動詞或動詞片語命名

例如：showModal（顯示彈窗）、save（儲存）

⁠

1.6 避免使用雙關語

避免使用同一個字詞代表兩個不同目的。

以「add」來說：

假設我們有許多類別的 add 方法，是用來「相加」或「相連兩個現有的值形成一個新的值」。

現在若還要再寫一個新的類別，此類別中有個方法會將「單一參數放入一個集合容器中」，那麼該方法的名稱還要叫做「add」嗎？

這時候可以考慮使用 insert （插入）或 append（附加）來做區隔不同情境。

⁠

1.7 添加有意義的上下文資訊

如下方資訊，合在一起看，能夠很清楚知道是「地址」資訊，而不會混淆。

但如果單獨看到 state 這個變數，還能夠迅速辨認這是「州」嗎？

// 名字

firstName = '';

// 姓氏

lastName = '';

// 街道

street = '';

// 門牌號碼

houseNumber = '';

// 城市

city = '';

// 州

state = '';

// 郵遞區號

zipCode = '';

其實更好的方式是用一個名為「Address」類別或物件去包裝，會更容易理解。