异想天开の博客

记录记录，分享分享

0%

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

发表于 更新于 分类于
本文字数： 2k 阅读时长 ≈ 2 分钟

名副其实 Use Intention-Revealing Names

如下是较好的例子（既有计量对象，也有计量单位）：

1
2
3
4
int elapsedTimInDays;
int daysSinceCreation;
int daysSinceModification;
int fileAgeInDays;

避免误导 Avoid Disinformation

  • 不要滥用 List、Array，它们有特定的含义，当形容一群/组东西时，要仔细思考是否要提及数据结构。

  • 提防使用外形相似度高的名称，当两个命名长度很长且相似时，区分它们要花时间

  • 在代码中，对同一概念或实体必须使用完全一致的命名和表达方式，才能传递清晰、无歧义的信息

    • 如混用 start/begin get/fetch controller/manager 等相似术语

    • 统一使用 start 表示启动，get 表示获取

  • 不要用 小写字母 l 和 大写字母 O 作变量名

做有意义的区分 Make Meaningful Distinctions

  • 不要用数字系列命名 Number-series naming (a1, a2, .. aN) is the opposite of intentional naming
  • 不要说废话
    • 如类名叫 Product，又出现一个 ProductInfo 或 ProductData 的类，虽然它们名称不同，含义却无区别。类似的还有 Customer 和 CustomerObject
    • variable不要出现在变量名中，table不要出现在表名中

使用能读出来的名称 Use Pronounceable Names

  • 编程是一种社交活动，如果读不出来如何讨论？

    • 反例：变量名 genymdhms (generation date, year, month, day, hour, minute,
      and second)，how to pronounce?

使用可搜索的名称 Use Searchable Names

对于单字母名称和数字常量，很难搜到，比如 搜索 数字7 很麻烦，但搜 MAX_CLASSES_PER_STUDENT 很容易。

  • 名称长度应与其作用域大小相对应

避免使用编码 Avoid Encodings

匈牙利语标记法 Hungarian Notation, HN

这种命名法要求明确写出类型，类型置于实际名称前，如 bBuzy 代表类型为 boolean、名称为 Busy 的变量

现在这种编码形式纯属多余

成员前缀 Member Prefixes

不必用 m_ 前缀标明成员变量

接口与实现 Interfaces and Implementations

  • ShapeFactory n ShapeFactoryImp 推荐

  • IShapeFactory n ShapeFactory 不推荐，I 被滥用，但是还是看团队吧

避免思维映射 Avoid Mental Mapping

经常出现在使用 问题领域术语(problem domain terms) 还是 解决方案领域术语 (solution domain terms)

明确是王道，编写的代码要易于理解

类名 Class Names

  • 应该是 名词 或 名词短语，如 Customer、WikiPage、Account and AddressParser

  • 反例：Manager、Processor、Data、Info

  • 类名不应是动词

方法名 Method Names

  • 应当是 动词 或 动词短语，如 postPayment、deletePage 或 save

  • 使用描述了参数的静态工厂方法名重载构造器，把构造器设置为 private

别抖机灵 Do not Be Cute

  • 别用 HolyHandGrenade，使用 DeleteItems。明确含义

  • 别用 whack() 表示 kill(), Say what you mean. Mean what you say

每个概念对应一个词 Pick One Word per Concept

跟避免误导里某一项比较类似，就是说给 每个抽象概念 选 一个词，并一以贯之

例如，同时使用 fetch、retrieve 和 get 在多个类中的同种方法命名，会令人困惑

一以贯之的命名法是天降福音

别用双关语 Do not Pun

避免将同一单词用于不同目的，同一个术语用于多个不同概念，就是双关语

使用解决方案领域名称 Use Solution Domain Names

优先使用 解决方案领域名称。你的读者是程序员，所以尽可能用计算机科学/工程相关术语，多用技术性的名称，如：

  • AccountVisitor 对于熟悉 访问者(Visitor)模式的程序员就很友好

  • JobQueue，我们知道这是个任务队列

使用问题领域名称 Use problem Domain Names

如果不好用 解决方案领域名称，就从所涉问题领域寻找名称。至少这个名称你可以从领域专家那知道其含义

添加有意义的语境 Add Meaningful Context

不要添加没用的语境 Do not Add Gratuitous Context

只要短名称足够清楚，就比长名称好，别给名称添加没用的语境

总结 Conclusion

明确 & 简洁 & 一以贯之 & 优先解决方案领域