好好命名啊！同学！Naming Convention 指南

Question

大家好，有一些 Naming Convention 的议题想跟各位分享与讨论

勒布朗克法则 (LeBlanc’s Law) 説：Later equals Never
你心想著待会儿再回来整理程式，但其实永远不会再回头改的

最近想要整理出一些 guideline 跟同仁分享，想说这样大家的程式可读性提升，对团队的合作会更好，不过我想先抛砖引玉，分享一些我整理出来的心得，希望大大们可以分享一下自己的 Naming Convention 或是有更好或更多的撰写程式的规范跟原则。

参考书籍：

• 易读程式之美学：提升程式码可读性的简单法则
• 无瑕的程式码(Clean Code)
• 软体建构之道(Code Complete) - 第 11 章变数名称的力量

---

下方先是我整理的资料分享，欢迎大家也分享自己的 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 指令动词列表 了，不过想说如果大家有更具体的应用，也可以分享一下，麻烦大家给点意见了

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