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，如易造成誤解，以下是我找到一些不錯的範例

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的理由

// 加上合理的限制 - 沒有人能讀那麼多文章
const int MAX_RSS_SUBSCRIPTIONS = 1000;

## 8.封裝條件
如果if()裡面有超長一串的判斷式，可讀性會超差，所以可以把這個判斷式用boolean變數裝起來再判斷

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)

--- 作者：學仁大大 ---