Skip to content
無瑕的程式碼 Clean Code
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 來命名參數,使用 controlNameAcontrolNameB 來區分會更符合「意圖」。

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」類別或物件去包裝,會更容易理解。
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.