Ronnie's Blog

代码整洁之道——有意义的命名

软件工程#编程规范

作者：程序员罗尼 ｜ 发布：2019-12-28 ｜ 原文：https://mp.weixin.qq.com/s/aOmlbSMsDoKCmTxK4BPhqw

第二章、有意义的命名
本文总结自《代码整洁之道》第二章
原则1、名副其实，可对比下面两段代码
public List<int[]> getThem() { final List<int[]> list1 = new ArrayList<>(); for (int[] x : list1) { if (x[0] == 4) { list1.add(x); } } return list1;}public List<int[]> getFlaggedCells() { final List<int[]> gameBoard = new ArrayList<>(); for (int[] cell : gameBoard) { if (cell[STATUS_VALUE] == FLAGGED) { gameBoard.add(cell); } } return gameBoard;}
2、避免误导

  • 避免出现类型，如 accountsList
  • 避免太相似的命名，如 XYZControllerForHandlingOfStrings 和 XYZControllerForStorageOfStrings
  • 注意小写 l 和大写 O 与整数 0 和 1 的相似性

3、做有意义的区分，避免如下问题

  • 数字序列：public int copy(int[] a1, int[] a2); -> public int copy(int[] source, int[] destination);
  • 近义词：Product，ProductInfo，ProductData，shit...
  • 冗余：iVariable，nameString，theMessage

4、使用读得出来的名称

  • genymdhms() -> generateTimestamp

5、使用可搜索的名称

  • 命名要有区分度，尽量避免单字母变量名，变量名称长度应与其作用域范围成正比

6、避免使用编码

  • 匈牙利标记法（当年没有编译器类型检查时出现的方法，用于标记变量类型，现在已经多余了）
  • 成员前缀
  • 接口和实现，避免 IShape 或者 ShapeImpl 的命名

7、避免思维映射

  • 直接了当表明意义，不要让人读代码的人还得将变量名翻译成他们熟知的名称

8、类名应该是名词或名词短语，不应该是动词
9、方法名应该是动词或动词短语，不应该是名词
10、别耍宝

  • 别用俚语或者文化背景相关的语言

11、每个概念对应一个词，并一以贯之

  • 不要又有 ProductManager，又有 DeviceDriver，还有 ProtocolController，统一一下使用 Manager 还是 Driver

12、别用双关语

  • 不要用一个词代表两个以上的概念

13、使用解决方案领域名称

  • 多用一些技术领域的名词，不要让同事每次去问客户各个名称的意义

14、使用源自所设问题领域的名称

  • 在上面的原则不适用时，采用这个原则，一般用于更贴近问题域的代码

15、添加有意义的语境

  • 一个小概念要隶属于一个大概念之下，给读者上下文

16、不要添加没用的语境

  • 如果短名称足够清楚，就不要使用长名称

小结上面的原则值得遵守，但是遵循好的原则也不保证能取出好的名称，还需要有良好的描述技巧和共同的文化背景，对于我们非英语国家的程序员来说，还得先学好英语
不管怎么说，取一个好名字是非常重要的，为了自己，也为了他人

END