2021年10月25日

變數命名好困難!6個程式碼命名建議,撰寫會說話的程式碼!

好的變數命名可以提升程式碼的可讀性,也能減少錯誤的發生,

最主要的宗旨是,讓看的人可以更容易理解程式碼內容

所以並沒有標準的做法,只要大家容易理解即可,最重要的是取得團隊共識。

 

以下歸納一些命名方式,第 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;

可以加上前綴,如 ishascan,讓變數的意圖更明顯。

# 建議
$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. 命名靈感來源

  1. 參考別人怎麼做

    很多時候團隊已經有很多約定成俗的用法,那就多參考一下既有的作法,不要創造新詞,最常看到的狀況是,明明同一個概念,在同一個系統裡面有好幾種不同的命名,看得眼花撩亂,例如商品,又是 goods 又是 item,又是 product,這樣缺乏一至性會造成程式碼混亂。

  2. 多利用線上辭典

    有時候可能會覺得自己英文不好,找不到適合的單字,但現在 Google 很方便,英文不好也沒關係,通常 Google 一下「XX 英文」就可以找到對應的單字了。

    不過值得注意的是,還是要稍微看一下單字的用法或解釋,因為有時候中文跟英文直翻是會有問題的。

    如果真的想要用縮寫,一樣可以問問 google,「xxx 縮寫」、「xxx abbreviation」,會出現比較正規的縮寫,這種使用上比較不容易有錯誤解讀。(abbreviation是縮寫的意思)

    另外 ChatGPT 現在也很聰明,也可以問問看它的意見XD

  3. 專業術語

    跟第一點有點像,在每個行業或領域中會有不同的專業術語,或是所謂的行話,這些術語通常早就有對應的英文了,可以從這些地方來找尋合適的命名,不需要再自創。

小結

取名字的當下很麻煩,但可以省去以後的麻煩,所以多花一點時間命名是值得的。

如果不知道該怎麼做,可以多多參考別人怎麼命名,

像是無瑕的程式碼Clean Code也花了一個章節討論命名的問題,

而我認為命名方式其實只是習慣問題,沒有對錯,

找出一個符合自己及團隊習慣的邏輯就好,然後保持一致性,對自己跟團隊都很有幫助!

 

本篇是開發系列文章,更多開發相關文章請參考→這裡

 

參考

The art of naming variables by @khoonie