Skip to content
無瑕的程式碼 Clean Code
前言
有意義的命名
常見的命名法
函式
註解
More
Share
Explore

icon picker
有意義的命名

​

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」類別或物件去包裝，會更容易理解。
1.1 命名須展現意圖
範例
1.2 避免誤導
1.3 產生有意義的區別
1、可以的話，盡可能不要使用「數字序列命名法」（a1 , a2, ... , aN）
2、無意義的字詞，也是一種無意義的區別。
1.4 使用能唸出來的名稱
1.5 命名規則
1.6 避免使用雙關語
1.7 添加有意義的上下文資訊
Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.