【代码】命名规范

该篇日志是一篇阅读材料的总结。文件下载地址：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. 如果你发现以前代码的名字不合理，不要因为担心’其他程序员可能会抱怨’而不去采取行动。事实上，一般来说他们会感谢你把名字修改地更加合理。