好的變數命名可以提升程式碼的可讀性,也能減少錯誤的發生,
最主要的宗旨是,讓看的人可以更容易理解程式碼內容,
所以並沒有標準的做法,只要大家容易理解即可,最重要的是取得團隊共識。
以下歸納一些命名方式,第 6 點有一些命名靈感的來源,可以往下看。這些建議沒有對錯的問題,只是個人習慣,提供給大家參考一下。
本篇是開發系列文章,更多開發相關文章請參考→這裡
1. 避免含糊不清的名稱
含糊不清的名稱,讓人不容易理解變數所代表的意義。
# 不建議
$a = 'Tom';
$b = 20;
清晰的變數名稱,可以減少猜測的過程。
# 建議
$name = 'Tom';
$userName = 'Tom';
$age = 20;
$userAge = 20;
函式命名也要清晰,避免籠統。
# 不建議
function setData($a) {}
# 建議
function setUserName($userName) {}
2. 陣列 - 單數複數
透過簡單的單數或複數變化,讓人直接明白這個變數是個陣列 (Array) 或清單 (List)。
# 不建議
$array = ['Tom', 'Jack', 'Rick'];
$user = ['Tom', 'Jack', 'Rick'];
# 可以這麼做
$userArray = ['Tom', 'Jack', 'Rick'];
# 建議
$userNames = ['Tom', 'Jack', 'Rick'];
foreach ($userNames as $userName) {
echo $userName;
}
3. 布林值
Boolean 是常用到的型別,通常搭配 if-else
使用。
# 不建議
$close = true;
$friend = false;
可以加上前綴,如 is
、 has
、 can
,讓變數的意圖更明顯。
# 建議
$isClosed = true;
$hasFriend = false;
if ($hasFriend) {
$this->user->getFriends();
}
4. 函式
函式通常代表一個指令,並且會有一些產出,發生一些改變,所以命名上要能夠看出這樣的變化。
# 不建議
function user()
function userYoung()
通常優先採用動詞
或是動詞+名詞/形容詞
的方式來命名。
# 建議
## 動詞
function get()
function update()
## 動詞 + 名詞
function getUsers()
function updateUser()
## 動詞 + 形容詞 (+ 名詞)
function getAll()
function getYoungUsers()
5. 縮寫
縮寫可以減少變數的長度,但是濫用縮寫會讓人混淆。特別是有些人喜歡自創縮寫,這個只有他自己能夠理解。
# 不建議
$un = 'Tom';
$userPh = '0910-123-123';
建議不要使用縮寫。
# 建議
$userName = 'Tom';
$userPhone = '0910-123-123';
如果不得不使用縮寫,請確保這樣的縮寫,在團隊內可以取得共識。
6. 命名靈感來源
參考別人怎麼做
很多時候團隊已經有很多約定成俗的用法,那就多參考一下既有的作法,不要創造新詞,最常看到的狀況是,明明同一個概念,在同一個系統裡面有好幾種不同的命名,看得眼花撩亂,例如商品,又是 goods 又是 item,又是 product,這樣缺乏一至性會造成程式碼混亂。
多利用線上辭典
有時候可能會覺得自己英文不好,找不到適合的單字,但現在 Google 很方便,英文不好也沒關係,通常 Google 一下「XX 英文」就可以找到對應的單字了。
不過值得注意的是,還是要稍微看一下單字的用法或解釋,因為有時候中文跟英文直翻是會有問題的。
如果真的想要用縮寫,一樣可以問問 google,「xxx 縮寫」、「xxx abbreviation」,會出現比較正規的縮寫,這種使用上比較不容易有錯誤解讀。(abbreviation是縮寫的意思)
另外 ChatGPT 現在也很聰明,也可以問問看它的意見XD
專業術語
跟第一點有點像,在每個行業或領域中會有不同的專業術語,或是所謂的行話,這些術語通常早就有對應的英文了,可以從這些地方來找尋合適的命名,不需要再自創。
小結
取名字的當下很麻煩,但可以省去以後的麻煩,所以多花一點時間命名是值得的。
如果不知道該怎麼做,可以多多參考別人怎麼命名,
像是無瑕的程式碼Clean Code也花了一個章節討論命名的問題,
而我認為命名方式其實只是習慣問題,沒有對錯,
找出一個符合自己及團隊習慣的邏輯就好,然後保持一致性,對自己跟團隊都很有幫助!
本篇是開發系列文章,更多開發相關文章請參考→這裡
參考
The art of naming variables by @khoonie