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