owned this note
owned this note
Published
Linked with GitHub
Naming Convention 指南
===
大家好,有一些 Naming Convention 的議題想跟各位分享與討論
勒布朗克法則(LeBlanc’s Law)説:Later equals Never
你心想著待會兒再回來整理程式,但其實永遠不會再回頭改的
最近想要整理出一些guideline跟同仁分享,想說這樣大家的程式可讀性提升,對團隊的合作會更好,不過我想先拋磚引玉,分享一些我整理出來的心得,希望大大們可以分享一下自己的 Naming Convention 或是有更好或更多的撰寫程式的規範跟原則。
參考書籍:
* [易讀程式之美學:提升程式碼可讀性的簡單法則](http://www.books.com.tw/products/0010584840?loc=006_055)
* [無瑕的程式碼(Clean Code)](https://www.slideshare.net/kylinfish/clean-code-72688451)
* [軟體建構之道(Code Complete) - 第 11 章變數名稱的力量](https://www.slideshare.net/boshen978/code-complete2-ch11the-power-of-variable-names)
---
下方先是我整理的資料分享,歡迎大家也分享自己的 Naming Convention
## 1. Boolean變數或function的命名方式
Boolean變數或function的開頭必須使用is, can, has, should,但如果本身是形容就不需要,像是enabled, done就無需用is開頭
使用肯定的Boolean變數名稱。避免雙重否定:if (!notFound) { }。
## 2. 用介系詞(of,for,from,on...)來組變數名稱
這件事情但起來單純,但很多時候大家都會忽視介系詞硬組變數名稱,像是daysUntilDeadline就有可能被命名成DeadlineDays,如易造成誤解,以下是我找到一些不錯的範例
```javascript=
var daysSinceModification = 3; // 修改後已過了3天
var workDaysPerWeek = 5; // 每週工作5天
var daysUntilDeadline = 10; // deadline前還剩10天
var customersInOrder; // 已經排序過的客戶資料
```
## 3.使用更具體的單位以及用詞
delayedTime代表的是delay的時間,但其實單位是秒數,所以命名上最好使用更具體的單位來優化這個命名,改寫成delayedSeconds會更好
如果是一筆員工的資料,原先變數取名是person,那最好將person重新命名為employee。person的含義太寬泛,employee則能表示員工的概念。
## 4.捨棄i,j,k,使用更好的Iterator
一般for迴圈中我們都會使用到i, j, k,這其實不是不行,但是如果i, j, k分別代表parent, children, toy,那就可以用pi, ci, ti來取代i, j, k,這樣程式碼不會變長太多,可讀性提高也較容易debug。
不過更好的方式就是直接使用`array.forEach()`或`array.map()`,會比iterator更清楚明瞭。
## 5.Function Name的prefix都是動詞
基本上function名稱全都是「動詞」開頭但如果像是`getCellSize()`或`calcCellSize()`,可以直接省略開頭的動詞,直接使用`cellSize()`即可,不過也有人堅持不能用名詞開頭,基本上團隊統一即可。
## 6.縮寫真的方便但並不是最好
因為不想打太長的變數或函數名稱,大家總是在縮寫,但是有些縮寫很容易讓人搞混,對於原本就在維護這份程式的工程師或許還好,但新進工程師會很容易困惑。
使用像是dns,url這些眾所皆知的詞沒問題,只有自己團隊才看得懂的縮寫,除非必要,不然盡量避免使用。
不過我覺得這個看情況而定,重點是一定要有一份解釋縮寫的文件比較好。
## 7.如何寫註解
* 在檔案的最前頭寫上整個程式檔案大致是如何運作的檔案註解
* 除了解釋程式運作的原理外,還可以描述為什麼要用這樣子的寫法來寫,可能是效能上的需求之類的
* 使用 `TODO` `FIXME` 等註解標籤,`TODO`可以標記尚未製作或是需要優化的部分,FIXME是不能運作需要修復的部分,其實我知道還有`HACK`, `XXX` 等標籤,不過我覺得好像都歸類在TODO比較方便,不知道大家的習慣是如何?
* 在設定常數的時候給予註解其實也能幫助理解,讓開發者更有概念,像是下面程式註解說明為什麼要設定為1000的理由
```javascript=
// 加上合理的限制 - 沒有人能讀那麼多文章
const int MAX_RSS_SUBSCRIPTIONS = 1000;
```
## 8.封裝條件
如果if()裡面有超長一串的判斷式,可讀性會超差,所以可以把這個判斷式用boolean變數裝起來再判斷
```javascript=
boolean isMan = (user.age >= 18 && user.gender == 'male');
if (isMan){
// 做一位男人該做的事>///<
}
```
---
## 其中最想請教大家的是function前方動詞的分類
Clean Code這本書上有說Pick one word for one abstract concept and stick with it.
不過比較沒人整理出較為通用的詞庫對應表,我知道這個本來就沒官方解答,但是我想聽聽看各位的經驗,整理出我自己的一套詞庫,以下是我目前整裡的詞庫
* fetch(retrieve):從遠端(透過API)獲取資料,例如:fetchUsers()
* load:從本地端加載資料,例如:loadFile()
* calculate / calc|通過計算獲取資料,例如:calcBMI()
* show:顯示物件,如showModal()、showDialog()
* remove:將資料之間的關係移除,資料本身還是會存在
* delete/destroy:將資料刪除,資料將會不存在
* on:定義event的時候使用,像是onClick,onChange
* handle:當onClick之類的event發生時所觸發的function,例如:handleClick,如果click後面有受詞的話,這將受詞移到click前方* 例如:handleButtonClick
剩下還有哪些詞是大家常用的呢?還請各位大大不吝分享,我在下面放一些可能會用到的詞,大家是怎麼給這些詞定義他專屬的concept,或是有哪些沒提到的也可以補充一下,我已經看過[微軟 PowerShell 指令動詞列表](https://msdn.microsoft.com/en-us/library/ms714428.aspx)了,不過想說如果大家有更具體的應用,也可以分享一下,麻煩大家給點意見了
get/set
create: insert append add append
edit: modify update
complete: finish done end
send: deliver, dispatch, announce, distribute, route
find: search, extract, locate, recover
start: launch, create, begin, open
make: create, set, build, genernate, compose, add, new
參考資料:[小酌重構系列[18]—重命名](http://www.cnblogs.com/keepfool/p/5510803.html)
--- 作者:學仁大大 ---