第二章 有意義的命名—Clean Code 閱讀筆記

MowLi 微風
微風飛翔
Published in
Jan 1, 2021
Photo by Jon Tyson on Unsplash

相信我們在寫程式的過程中已經為變數、函式等命名過無數次,其中也不乏取過一些沒有實質意義或者自己覺得有趣的名稱,或者某一個 Bug 跑到很幹的時候會直接發洩在變數的名稱上面,以洩我心頭之恨。

本書提到「命名」這件事必須認真嚴肅地去看待它,這讓我想到一個蠻貼切的例子:每次玩新遊戲一開始最花時間的絕對是想自己 ID 到底要取什麼。

而一個好的命名最重要的是能夠清楚表達你的意圖,可以讓未來審視程式碼的人(包括自己)帶來可讀性,節省理解程式碼所花費的時間。

以下為筆者讀後所收穫的一些內容,提及大致的概念及盡量將書籍闡述的內容轉變為自己的話,原文還請大家多多支持該書籍。

命名具備的要點-名符其實

良好的命名不需要註解就能清楚表達意圖

不要以過於簡單的字母 (a, b) 或序列命名法 (arr1, arr2) 命名

例如 arr1 = [18.5, 18.1, 17.3, 16.8…] 雖然可以知道這是一個儲存數字的陣列,但如果將陣列命名為 todayHourlyTemperture,是否比 arr1 或者 temp(溫度的簡寫) 能更清楚了解這是今日每小時的氣溫,而不用再去做多餘的猜測。

盡量以唸得出來的名稱

以書中舉的例子,某間公司寫了一個 Date 型態的變數名為 genymdhms,即為年、月、天、時、分、秒所組成的日期,由於這種發音方式必須自己創造(gen why emm dee aich emm ess),沒聽過的人完全不知道這是什麼東西,遇到新的開發者就需要重新解釋一遍。

因此,還不如把名稱取作產生時間戳(generationTimestamp )較為直白易懂。

避免誤導

(1) 外觀

如果你以前很常買遊戲橘子的點數卡,就會知道不可能有 O 跟 L 的儲值字母,只有 0 跟 1,因為這會造成你無法「一眼區別」到底是什麼字,同樣地在撰寫程式中也需要避開相同的問題。

(2) 語意

某些程式語言的基本型態會與人們所理解的事物混淆,例如帳號的變數名稱取名為 AccountList,有可能會讓程式設計師誤以為這是一個 List 型態的變數。

避免無意義的區別

「相同意思的字詞」會發生無意義的區別,例如我們沒有辦法清楚地得知 AccountData 與 AccountInfo 有什麼不同之處,似乎都可以表示帳戶資訊。

而「多餘的字眼」同樣會產生這種無意義的區別,例如把正常都會是字串型態的姓名變數取名為 NameString 不會比直接取名為 Name 好。

具備效度-表達之精準性

書中在這個部分提及「不要用同一種字詞來表達兩種不同的目的」,對於我來說就是效度的意思,簡單來說就是你所取的命名有沒有精準地表達、闡述到重點。

例如 add 其實涵蓋的意義有點廣,可以表示將兩個數值相加,理論上 add 也可以代表將一個數值放入一個容器之中,但後者可以用 insert 來區別出其中的差異。

作者認為若要達成該條件,自身在撰寫程式必須要有一致性,對於同一種概念皆使用同一種字詞,讓別人以後一看到 insert 就知道我要幹嘛(目的)。

類別、物件、方法之命名

其他注意事項

人可以有幽默感,但不要用在程式的命名上

避免取一些幽默、娛樂的名稱,例如:skr,儘管能讓人在煩雜的程式碼中讓人會心一笑,但能清楚描述意圖還是比較重要。

盡量以 Domain Knowledge 的方式命名

閱讀自己程式碼的人大多是程式設計師,使用 Design Pattern 及一些 CS 術語 (Tree、Queue…等) 是不錯的變數命名選擇。

若無法以 CS 術語來命名的項目,可採用該項目在領域中的術語來命名,例如:EPS(每股盈餘),新進的開發人員不懂時就可請教領域專家作解釋。

總結

以前在命名時沒有什麼概念,只覺得能看得懂就好,也犯了不少 Clean Code 中所提及的錯誤,雖然本章書中講述的概念很多都是看完就能大致理解的常理,但實際上困難的是養成取一個好命名的習慣。

--

--