在 软件中随处可见命名：要给变量、函数、参数、类和封包命名，还要给源代码及源代码所在目录命名，甚至还有jar文件、war文件和ear文件命名。

但是，看似简单的命名，也是让不少程序员头疼的问题。 有一些小伙伴，在进行变量命名的时候，对于自己熟悉的英文，可能还会用英文命名一下，如果需要命名的部分不会用英文表达，或许就直接用拼音了。

有的童鞋一下想不起来怎么命名，直接用拼音直接用aa，bb等这样没有任何代表意义的字母来命名，可读性非常差，可能自己今天写的，一个星期后回来再看，也忘记其具体代表的含义了。

因此，许多人在写代码之前，总会在想啊想啊，用什么命名法好呢？对于经常在C++、Java、Python等主流语言上切换的强迫症来说，换个语言换种命名风格简直不要太混乱。

既然有这么多命名要做，不妨做好它。本期内容中，异步君为大家带来了起个好名字应遵从的几条简单规则，一起来看看吧

— 01 —

名副其实

名副其实说起来简单。我们想要强调，这事很严肃。选个好名字要花时间，但省下来的时间比花掉的多。注意命名，而且一旦发现有更好的名称，就换掉旧的。这么做，读你代码的人（包括你自己）都会更开心。

变量、函数或类的名称应该已经答复了所有的大问题。它该告诉你，它为什么会存在，它做什么事，应该怎么用。如果名称需要注释来补充，那就不算是名副其实。

 int d;  // elapsed time in days  

名称d什么也没说明。它没有引起读者对时间消逝的感觉，更别说以日计了。我们应该选择指明了计量对象和计量单位的名称：

 int elapsedTimeInDays;int daysSinceCreation;int daysSinceModification;int fileAgeInDays;  

选择体现本意的名称能让人更容易理解和修改代码。下列代码的目的何在？

 public List<int[]> getThem() {
  List<int[]> list1 = new ArrayList<int[]>();
  for (int[] x : theList)
    if (x[0] == 4)
      list1.add(x);
  return list1;}  

为什么难以说明上述代码要做什么事？里面并没有复杂的表达式，空格和缩进中规中矩，只用到三个变量和两个常量，甚至没有涉及任何其他类或多态方法，只是（或者看起来是）一个数组的列表而已。

问题不在于代码的简洁度，而在于代码的模糊度：即上下文在代码中未被明确体现的程度。上述代码要求我们了解类似以下问题的答案：

（1）theList中是什么类型的东西？

（2）theList零下标条目的意义是什么？

（3）值4的意义是什么？

（4）我怎么使用返回的列表？

问题的答案没体现在代码段中，可代码段就是它们该在的地方。比方说，我们在开发一种扫雷游戏，我们发现，盘面是名为theList的单元格列表，那就将其名称改为gameBoard。

盘面上每个单元格都用一个简单数组表示。我们还发现，零下标条目是一种状态值，而该种状态值为4表示“已标记”。只要改为有意义的名称，代码就会得到相当程度的改进：

 public List<int[]> getFlaggedCells()  {
  List<int[]> flaggedCells = new ArrayList<int[]>();
  for (int[] cell : gameBoard)
    if (cell[STATUS_VALUE] == FLAGGED)
      flaggedCells.add(cell);
  return flaggedCells;}  

注意，代码的简洁性并未被触及。运算符和常量的数量全然保持不变，嵌套数量也全然保持不变，但代码变得明确多了。

还可以更进一步，不用int数组表示单元格，而是另写一个类。该类包括一个名副其实的函数（称为isFlagged），从而掩盖住那个魔术数[1]。于是得到函数的新版本：

 public List<Cell> getFlaggedCells()  {
  List<Cell> flaggedCells = new ArrayList<Cell>();
  for (Cell cell : gameBoard)
    if (cell.isFlagged())
      flaggedCells.add(cell);
  return flaggedCells;}  

只要简单改一下名称，就能轻易知道发生了什么。这就是选用好名称的力量。

— 02 —

避免误导

程序员必须避免留下掩藏代码本意的错误线索。应当避免使用与本意相悖的词，例如，hp、aix和sco都不该用作变量名，因为它们都是Unix平台或类Unix平台的专有名称。即便你是在编写三角计算程序，hp看起来是一个不错的缩写[2]，但那也可能会提供错误信息。

别用accountList来指称一组账号，除非它真的是List类型。List一词对程序员有特殊意义。如果包纳账号的容器并非真是一个List，就会引起错误的判断。

所以，用accountGroup或bunchOfAccounts，甚至直接用accounts都会好一些。

提防使用外形相似度较高的名称。例如，想区分模块中某处的XYZControllerFor-EfficientHandlingOfStrings和另一处的XYZControllerForEfficientStorage-OfStrings，会花多长时间呢？这两个词的外形实在太相似了。

以同样的方式拼写出同样的概念才是信息。拼写前后不一致就是误导。我们很享受现代 Java 编程环境的自动代码完成特性。键入某个名称的前几个字母，按一下某个热键组合（如果有的话），就能得到一列该名称的可能形式。

假如相似的名称依字母顺序放在一起，且差异很明显，那就会相当有助益，因为程序员多半会压根不看你的详细注释，甚至不看该类的方法列表就直接看名字挑一个对象。

误导性名称真正可怕的例子，是用小写字母l和大写字母O作为变量名，尤其是在组合使用的时候。当然，问题在于它们看起来完全像是常量“壹”和“零”。

 int a = l;if (O == l)
  a = O1;else
  l = 01;  

读者可能会认为这纯属虚构，但我们确曾见过充斥这类名称的代码。有一次，代码作者建议用不同字体写变量名，好显得更清楚些，但前提是这种方案得要通过口头和书面传递给未来所有的开发者才行。后来，只是做了简单的重命名操作，就解决了问题，而且也没引起别的问题。

— 03 —

做有意义的区分

如果程序员只是为满足编译器或 解释器 的需要而写代码，就会制造麻烦。例如，因为同一作用范围内两样不同的东西不能重名，你可能会随手改掉其中一个的名称，有时干脆以错误的拼写充数，结果就会出现在更正拼写错误后导致编译器出错的情况。

光是添加数字系列或是废话远远不够，即便这足以让编译器满意。如果名称必须相异，那么其意思也应该不同才对。

以数字系列命名（a1、a2…aN）是依义命名的对立面。这样的名称纯属误导——完全没有提供正确信息，没有提供导向作者意图的线索。试看：

 public static void copyChars( char  a1[], char a2[]) {
  for (int i = 0; i < a1.length; i++) {
    a2[i] = a1[i];
  }}  

如果参数名改为source和destination，这个函数就会像样许多。

废话是另一种没意义的区分。假设你有一个Product类，如果还有一个名为ProductInfo或ProductData的类，那它们的名称虽然不同，意思却无区别。Info和Data就像a、an和the一样，是意义含混的废话。

注意，只要体现出有意义的区分，使用a和the这样的前缀就没错。例如，你可能把a用在域内变量，而把the用于函数参数[5]。但如果你已经有一个名为zork的变量，又想调用一个名为theZork的变量，麻烦就来了。

废话都是冗余。 variable 一词永远不应当出现在变量名中。table一词永远不应当出现在表名中。NameString会比Name好吗？难道Name会是一个浮点数？如果是这样，就违反了关于误导的规则。

设想有一个名为Customer的类，还有一个名为CustomerObject的类，它们的区别何在呢？哪一个是表示客户历史支付情况的最佳方式？

有一个应用反映了这种状况。为当事者讳，我们改了一下，不过犯错的代码的确就是这个样子：

 getActiveAccount(); getActiveAccounts(); getActiveAccountInfo();  

程序员怎么知道该调用哪个函数呢？

如果缺少明确约定，那么变量moneyAmount与money就没区别，customerInfo与customer没区别，accountData与account没区别，theMessage也与message没区别。要区分名称，就要以读者能鉴别不同之处的方式来区分。

— 04 —

使用读得出来的名称

人类长于记忆和使用单词。大脑的相当一部分就是用来容纳和处理单词的。单词能读得出来。人类的大脑中有那么大的一块地方用来处理言语，若不善加利用，实在是种耻辱。

如果名称读不出来，讨论的时候就会像个傻鸟。“哎，这儿，鼻涕阿三喜摁踢（bee cee arr three cee enn tee）[6]上头，有个皮挨死极翘（pee ess zee kyew）[7]整数，看见没？”这不是小事，因为编程本就是一种社会活动。

有一家公司，程序里面写了一个genymdhms（生成日期，年、月、日、时、分、秒），他们一般读作“gen why emm dee aich emm ess”[8]。我有见字照拼读的恶习，于是开口就念“gen-yah-mudda-hims”。

后来好些设计师和分析师都有样学样，听起来傻乎乎的。我们知道典故，所以会觉得很搞笑。搞笑归搞笑，实际是在强忍糟糕的命名。在给新开发者解释变量名的意义时，他们总是读出傻乎乎的自造词，而非恰当的英语词。比较

 class DtaRcrd102 {
  private Date genymdhms;
  private Date modymdhms;
  private final String pszqint = "102";
  /*  ...  */};

和
class Customer {
  private Date generationTimestamp;
  private Date modificationTimestamp;
  private final String recordId = "102";
  /*  ...  */};  

现在读起来就像人话了：“喂，Mikey，看看这条记录！生成时间戳（generation timestamp）[9]被设置为明天了！不能这样吧？”

— 05 —

使用可搜索的名称

对于单字母名称和数字常量，有一个问题，就是很难在一大篇文字中找出来。

找MAX_CLASSES_PER_STUDENT很容易，但想找数字7就麻烦了，它可能是某些文件名或其他常量定义的一部分，出现在因不同意图而采用的各种表达式中。如果该常量是个长数字，又被人错改过，就会逃过搜索，从而造成错误。

同样，e也不是一个便于搜索的好变量名，它是英文中最常用的字母，在每个程序、每段代码中都有可能出现。由此而见，长名称胜于短名称，搜得到的名称胜于用自造编码代写就的名称。

窃以为单字母名称仅用于短方法中的本地变量。名称长短应与其作用域大小相对应 [N5]。若变量或常量可能在代码中多处使用，则应赋予其便于搜索的名称。再比较：

 for (int j=0; j<34; j++) {
  s += (t[j]*4)/5;}

和
int realDaysPerIdealDay = 4;const int WORK_DAYS_PER_WEEK = 5;int sum = 0;for (int j=0; j < NUMBER_OF_TASKS; j++) {
  int realTaskDays = taskEstimate[j] * realDaysPerIdealDay;
  int realTaskWeeks = (realTaskdays / WORK_DAYS_PER_WEEK);
  sum += realTaskWeeks;}
  

注意，上面代码中的 sum 并非特别有用的名称，不过至少搜得到它。采用能表达意图的名称，貌似拉长了函数代码，但要想想看，WORK_DAYS_PER_WEEK比数字5好找得多，而列表中也只剩下了体现作者意图的名称。

— 06 —

避免使用编码

编码已经太多，无谓再自找麻烦。把类型或作用域编进名称里面，徒然增加了解码的负担。没理由要求每位新人都在弄清要应付的代码之外（那算是正常的），还要再搞懂另一种编码“语言”。这对解决问题而言，纯属多余的负担。带编码的名称通常也不便发音，容易打错。

匈牙利语标记法

在往昔名称长短很重要的时代，我们毫无必要地破坏了不编码的规矩，如今后悔不迭。 Fortran 语言要求首字母体现出类型，导致了编码的产生。 BASIC 语言的早期版本只允许使用一个字母再加上一位数字。 匈牙利语 标记法[10]（Hungarian Notation，HN）将这种态势愈演愈烈。

在Windows的 C语言 API的时代，HN相当重要，那时所有名称要么是一个整数句柄，要么是一个长指针或者void指针，要不然就是string的几种实现（有不同的用途和属性）之一。那时候编译器并不做类型检查，程序员需要匈牙利语标记法来帮助自己记住类型。

现代 编程语言 具有更丰富的类型系统，编译器也记得并强制使用类型。而且，程序员趋向于使用更小的类、更短的方法，好让每个变量的定义都在视野范围之内。

Java程序员不需要类型编码，因为对象是强类型的，代码编辑环境已经先进到在编译开始前就能监测到类型错误的程度！所以，如今HN和其他的类型编码形式都纯属多余。它们增加了修改变量、函数或类的名称或类型的难度，它们增加了阅读代码的难度，它们制造了让编码系统误导读者的可能性。

 PhoneNumber  phoneString;//  name not changed when type changed！  

成员前缀

也不必用m_前缀来标明成员变量。应当把类和函数做得足够小，以消除对成员前缀的需要。你应当使用某种可以高亮或用颜色标出成员的编辑环境。

 public class Part {
  private String m_dsc; // The textual description
  void setName(String name) {
    m_dsc = name;
  }}--------------------------------------------------------------------------------------public class Part {
  String description;
  void setDescription(String description) {
    this.description = description;
  }}  

此外，人们会很快学会无视前缀（或后缀），而只看到名称中有意义的部分。代码读得越多，眼中就越没有前缀。最终，前缀变作了不入法眼的废料，变作了旧代码的标志物。

接口和实现

有时也会出现采用编码的特殊情形。比如，你在做一个创建形状用的抽象工厂（Abstract Factory），该工厂是一个接口，要用具体类来实现。你怎么来命名工厂和具体类呢？IShapeFactory和ShapeFactory吗？我喜欢不加修饰的接口。前导字母I被滥用到了说好听点儿是干扰，说难听点儿根本就是废话的程度。

我不想让用户知道我给他们的是接口，而就想让他们知道那是一个ShapeFactory。如果在接口和实现中必须选其一来编码的话，我宁肯选择实现。ShapeFactoryImp，甚至是丑陋的CShapeFactory，都比对接口名称编码好。

-END-

代码整洁之道

作者： [美] 罗伯特·C. 马丁（Robert C. Martin）

译者： 韩磊

内容简介：

软件质量，不但依赖架构及项目管理，而且与代码质量紧密相关。这一点，无论是敏捷开发流派还是传统开发流派，都不得不承认。

本书提出一种观点：代码质量与其整洁度成正比。干净的代码，既在质量上较为可靠，也为后期维护、升级奠定了良好基础。作为编程领域的佼佼者，本书作者给出了一系列行之有效的整洁代码操作实践。这些实践在本书中体现为一条条规则（或称“启示”），并辅以来自实际项目的正、反两面的范例。只要遵循这些规则，就能编写出干净的代码，从而有效提升代码质量。

本书阅读对象为一切有志于改善代码质量的程序员及技术经理。书中介绍的规则均来自作者多年的实践经验，涵盖从命名到重构的多个编程方面，虽为一“家”之言，然诚有可资借鉴的价值。