基礎但不簡單: 變數命名規則

LSZ
程式愛好者
Published in
7 min readSep 4, 2020

--

對於電腦來說,變數名稱的好壞並不重要。真正重要的好壞,是變數命名習慣將影響整個程式的可讀性及可維護性。

因為變數是給人看的。

下面舉例以javascript為主,每個語言在變數命名的規範上略有不同。

Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. …[Therefore,] making it easy to read makes it easier to write. — Robert C. Martin

以上的意思是讀寫時間比例超過10:1,擁有好的可讀性將會使程式開發效率大幅上升。

命名習慣的好壞可由以下2點判斷:

  1. 可讀性
  2. 一致性

可讀性

變數是影響可讀性最大的一環,例如以下 function,可以看一下這 function的功能是什麼。

function a(b) {
let c = parseInt(b / 3600);
let d = parseInt(b % 3600 / 60);
let e = parseInt(b % 3600 % 60);
return `${c}:${d}:${e}`;
}

上述的程式碼在無註解的情況不容易理解有什麼功能,若是面對更複雜的 function 或是整個程式,我們會很難讀懂程式的運作。

以下是有命名後的 function:

function convertSecondsToHMS(totalSeconds) {
let hours = parseInt(totalSeconds / 3600);
let minutes = parseInt(totalSeconds % 3600 / 60);
let seconds = parseInt(totalSeconds % 3600 % 60);
return `${hours}:${minutes}:${seconds}`;
}

一致性

一致性是指必須要用相同的規則命名整個程式的變數,可以是合作的工程師口頭約定也可以是一份 code style 文件。

如果採用了駝峰式就必須一直使用駝峰式,如果將使用者名稱命名成userName 就不要在中途改成 accountName 或只剩下 user。

變數命名規則

變數的字元一般使用英文或數字,特殊符號$_,不可數字開頭,可以包含拉丁字母或是中文 (合法的 unicode 字元,只是不會這樣用),但不可是保留字 ( reserved word)。

//以下是合法變數命名,實際上不會這樣做
let ಠ_ಠ = 1;
let 測試 = 1;
let _ts12et$ = 1
// 不合法的
let 1test = 1;
let @test = 1;
let break = 1; //保留字
// 正常的
let userId = 1;
let user_id = 1;

主流命名方式

駝峰式命名法 (Camel Case)

第一個字母為小寫,之後每一個單字的開頭為大寫,不包含空格。例如:

  • userName
  • fileName

Snake Case 命名法

單字皆為小寫,單字以底線_分離。例如:

  • user_name
  • file_name

Camel Case 和 Snake Case 都是較多被採用的命名方式,擇一使用即可。

Pascal 命名法 (Pascal Case)

跟 Camel Case 類似,只是第一個字要大寫。例如:

  • UserName
  • FileName

Kebab Case 命名法

跟Snake Case類似,單字以減號-分離。例如:

  • user-name
  • file-name

常用地方:

html的裡面的class和id
<div class="col-md-6" id="user-password"></div>
restful api的分隔符號
http://localhost/api/order-list

Screaming Case 命名法

跟Snake Case類似,單字皆為全大寫。例如:

  • USER_NAME
  • FILE_NAME

常用地方:

常量變數(constant variable)
MAX_EXECUTION_TIME=60
枚舉名稱(enum)
enum Level {
LOW,
MEDIUM,
HIGH
}

匈牙利命名法 (Hungarian notation)

將型態名稱放在最前面,後面才是變數名稱,根據維基百科一開始是BCPL語言在用,因為該語言只有一個叫機器字的資料型態,現在已很少用。例如:

  • iSize: 整數型態
  • bCheck: boolean型態

變數命名參考手冊

好的命名並不容易,當場景越來越複雜時,就會越難使用幾個單字描述該變數的功能。

以下是可以參考的規則:

  1. 不要使用長度超過50字元的變數,太長的變數會使程式碼可讀性降低,在清楚表達的前提下,名稱越短越好。
  2. 變數的組成應為多個形容詞、名詞組成,避免使用單一動詞當作變數,如create = 1。
  3. 區分單複數,例如: user是單數,users、userArray、userList、userCollection是複數。
  4. 不要加入無意義的前綴,如: m_name,這寫法通常代表一個 class 下的成員變數(member variable) name,一個class底下的 name 只可能是成員變數,使用 name 即可。
  5. 盡量不要使用無意義的單字,data、temp、value、等干擾詞,若是遍及整份程式碼,會掩蓋了具有意義的單字。
  6. 使用可以發音的單字,在溝通時若選用難以發音的單字,就會增加溝通的難度。
  7. 若要使用無意義的單字或是單個字母如: i, j, data 等,要確保變數的作用域在短行數的程式碼內,如 for loop 或一個 if block,當變數的作用域越廣則須越長的名稱清楚地描述該變數的意義,名稱的長度應與作用域範圍大小成正比。
  8. 推薦使用 Camel Case 或是 Snake Case 命名方式。
  9. 使用英文單字而不是類似中文拼音的方式或是自創的單字,如 biaoGe(中文拼音的表格) 。
  10. 使用有意義或公認的縮寫而不是只有少部分人才懂得縮寫,如果不是就應該使用全寫。公認的縮寫像是 id (identity)、int (integer)這類,不好的縮好像是 order system 裡面的 user 簡寫成 os_user 或 soUser,比較好的是system_order_user或 systemOrderUser。
  11. 當進行開發時,如果有更適合的變數名稱,就去更改他,不要忌諱隨時改名。
  12. 選擇好一個單字就使用到底,如: 使用了 user 中間就不要換成 member,當定義一個動作為 get,就不要換成 fetch 或 retrieve等同義字。
  13. 使用正確的資訊專業術語,如某種演算法或是 Factory、Interface,看程式碼的人都具有專業背景,使用專業術語更能清楚表達,若使用錯誤將產生極大的混淆。
  14. 在命名時,應注重可搜索性,開發上很難避免搜尋變數,若是將大量的變數命名成 data,即使不衝突也會造成搜尋上的困擾。
  15. 標示變數的相關訊息可幫助了解變數的狀態,例如: boolean 的變數取名為 isLogin,是 object 的變數取名為 userObj,是 array 的變數取名為 userList或是 userArray,比起 users 要清楚一點,相關訊息並不是指型態,所以不會出現 userString 或是 strUser 等(類似匈牙利命名法 Hungarian Notation)。
  16. boolean的變數可使用 is/has/can + 名詞或形容詞或 enable/disable + 動詞,以表達行為,如:isUser、hasName、canSignup、hidden、available、enableOrder、disableUpate,若是 function 返回 boolean值可在前面加check,如: checkHasName()、checkIsUser()。
  17. 變數命名方式因語言而異,用什麼語言就用那語言推薦的命名 style。

--

--