代码命名规范

该篇日志是一篇阅读材料的总结。文件下载地址： https://class.stanford.edu/c4x/Engineering/CS-144/asset/Naming.pdf

（也可从百度云盘下载： http://pan.baidu.com/s/1hqf6KIw）。总结以下：

1. 名称应该反映代码做者的目的。
2. 1. 这节省了没必要要的注释（如 int t; // Time since born in days 能够改成 int daysSinceBorn;），并使代码变得易于读懂。易读和易于互相讨论，这将是如下所有命名规范的关注点。关于注释的另外一个须要注意的问题：时间紧张时，没有多少人会读注释，而是由名称猜含义。
   2. 避免出现魔术数字，用宏定义取代数字；避免’莫名其妙的操做’，各类判断或循环控制语句读起来应该尽可能像正常的句子。
3. 避免歧义。
4. 1. 计算机科学中有一些字母组合，由于广为人知全部具备了约定俗成的含义，如hp，aix，list等。因此一个“nameList”的变量，会立刻给人以“这是一个链表”的印象；若是它事实上不是一个链表，那么“AccountGroup”就是更好的名字。
   2. 另外一种致使歧义的缘由是两个名字长得太像。好比“ThisIsOneName”与“ThisIsOnName”区别小且不宜一眼看出。另外，小写L（l）和1在有些编辑器里很像，0和O也是如此；应留心这一问题。
5. 不一样名称的含义应该有明显的区别。如“StellarInfo”和“StellarData”在含义上没有什么区别，若是用来表明两个不一样的东西，则很容易让使用者（本身或他人）用错。这能够认为是上面讲的‘歧义’的一个变种（不是跟约定的名称冲突，而是在语义上和本身的其余名称冲突）。
6. 与上面相关的，一个概念应该使用同一个单词。好比有两个类，Dog和Cat，那么用’feet’和’paws’来分别表示“狗的爪”和“猫的爪”就不是好习惯，由于这样你就不得不记清楚究竟狗和猫哪个对应feet。可是--
7. 若是一个单词对不一样对象有不一样的含义，不能为了’一致性’而使用，而是应该对特定的类型选择最为合适的名字。好比两个数字相加，用’add’；向一个列表中加入元素，彷佛也能够用’add’，但意义却与上面的两者’相加’明显不一样。故应考虑’append’。
8. 使用可以拼读的名字。好比“tpshms”就没办法拼读，这样在跟其余程序员讨论时，就只能“tee-pee-es-aich-em-es”这样一个字母一个字母来讲，费时费力；相反的，“userId”就赞成多了。
9. 名字应易于搜索。这具备很明显的实际意义：快速定位到感兴趣的变量的定义处，对高效地理解一段代码相当重要。不易搜索的变量名包括单独的数字和字母个数少的字符串等。好比，5这个数字就很难grep到目标位置，但定义一个宏：MIN_ELEMENT_NUMBER就很容易搜索到。原则上名字的长度应大体和其所在的域的代码长度成正比；但不管如何，尽可能用描述性强的名字。
10. 不要使用表示类型的前缀。匈牙利命名法在数据类型较少的时代是有用的，但现代编程语言，类型多种多样，且能够互相嵌套，用匈牙利命名法或相似的命名法，只会致使不少不容易发音，且本质上没人关心的前缀。一句话：命名时只关注该变量的含义，不要管它的类型。
11. 避免无心义的命名。如循环指标使用i,j,k就是坏习惯。它们没有任何意义。
12. 不要耍小聪明。好比使用特有的典故（#define hu_lu_wa 7）；但阅读代码的人可能来自不一样的文化，彻底不懂这里面的幽默，所以只会致使困惑。实在忍不住要写，就把幽默放到注释里去，不忙的人或许会读一读。
13. 使用合适的动词-名词结构。好比一个类的method，能够命名为getName（这种首个单词小写，后面单词首字母大写的方式，称为camel casing）；名称更改操做能够是’fred’.changeNameTo(“mike”)，注意到里面甚至用了介词to--目的只有一个：让一个函数语句像是一个正常的句子。
14. 明确两类命名方式。一类命名反应技术细节，一类命名描述特定对象。基本精神是，位于软件结构的最外层函数应该更反映对象自己的性质，好比car.weight()或star.age()；而底层实现应该与解决方案相关—这是很天然地，由于一般底层实现是不依赖于具体对象的，好比经常使用的库里的函数。
15. 对可能形成歧义的变量名添加上下文。好比一个变量名为tree，就很难肯定它是数据结构里的各类树，仍是森林里的一棵树。解决方案是把它放到一个类/名字空间/函数里面；或者加前缀也是个办法，好比oak_tree。
16. 不要添加无谓的前缀。好比你要给学校写个网关软件，里面的地址命名为sjtuAddress就不是好习惯；由于全部的变量都具备sjtu这一属性，因此干脆都不要写。
17. 与上面相关的一点：越具备描述性越好，并不意味着名字里的字母越多越好；事实上，在一样清晰地状况下，字母越少越好。
18. 若是你发现之前代码的名字不合理，不要由于担忧’其余程序员可能会抱怨’而不去采起行动。事实上，通常来讲他们会感谢你把名字修改地更加合理。