[笔记] 代码整洁之道3：章2有意义的命名

修改命名是一种低成本提升代码可读性的方法，怎么起有意义的名呢？参考如下方法：

名副其实

    变量、函数或类的名称应该告诉你，它为什么会存在，它做什么事，应该怎么用。如果连名称都需要注释来补充，那就名不副实了。例如下面这种我们惯用的简洁命名大法：

int d;  // 消失的时间，以日计

    变量d本身没有任何意义，很难让人想到注释的深意。改良的话，应该选择指明计量对象和计量单位的名称：

int elapseTimeInDays;
int daySinceCreation;

    很多时候我们写的代码大都言简意赅，缺少含义，例如：

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

    这段代码格式ok，逻辑上读起来也没什么问题，但是里边很难看到响应的场景逻辑、表达的细节和隐含的需求。里边三个变量，两个常量，让人不明所以。在做什么事？处理的是什么数据？返回什么数据？让人更难捉摸。假设当前开发的是一个扫雷游戏，theList就是棋盘，起名gameboard一秒带入。棋盘上没有单元格用一个数组表示其状态，0是一种状态，假设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;
}

    更新之后有点容易读懂了。cell[STATUS_VALUE] == FLAGGED 这里还包含一个逻辑，这个逻辑写在这里有点点增加代码的复杂性（含义上的），可以把这个逻辑分离到单独的类里，从而掩盖这里的细节。利用定义类Cell代替int[]数组，定义方法isFlagged()判定逻辑。

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

避免误导

    命名必须避免歧义和误导。例如：

• 专有名称，编程语言本身的关键词，如class；系统专有名词或命令，如cd
• 带类型名，别用accountList来指一组账号，除非真的是List类型。
• 命名之间太相似，例如thisIsYourFirstName和thisIsYourLastName
• 单独的l或O，如l=1; O=0;都要费好久的眼力。

做有意义的区分

    注意数字型命名和废话型命名。数字型命名a1, a2, a3这种命名完全看不懂。废话型命令即有包含类型的，如NameString不比Nmae多表达什么信息；也有包含模糊词语的，如accountData表达的信息不比account多。

使用读得出来的单词，而非晦涩的自造词

使用可搜索的名称

    对于作用域大的名称，尽量使用有含义的名称便于搜索，作用域小的名称可以简短些。

避免使用编码（如类型前缀）

    在早期的编码规范中，一种受推崇的命名方式是加前缀，例如String m_dsc表示类变量，class IFactory表示是接口类，它们可以被更明确或简洁的表达为description和Factory

添加有意义的语境（可以使用有意义的前缀）

    例如一组与地址有关的变量firstName, state, city等，可以命名为addrFirstName, addrState, addrCity。但如果这些变量本身被封装在独立且纯净的Address类里，则可以考虑不加前缀。

避免思维映射

    在循环中用ijk做变量名在小作用域是可取的，但并不理想，最好使用映射到具体含义的变量名，不然可能得时刻琢磨，比如多层循环里去想这ijk分别代表啥…

类名一般是名词或名词短语，方法名是动词或动词短语

一个概念用一个词命名，一以贯之，不要用多个类似的词

添加有语境的前缀方便理解

    例如addrFirstName，表示地址里的名字。但不要添加无用的语境，比如软件简称的标示。

注：本文部分摘引自《代码整洁之道》Robert C Martin 著 韩磊 译