软件开发命名指南

时间 2019-11-08

标签软件开发命名指南繁體版

原文原文链接

摘译自 Effectively Naming Software Thingies (by Sagi Rabinovich@Medium)html

代码是写给人看的，好的命名对提升代码的可读性相当重要。java

命名是一门艺术，须要有良好的描述技巧，有些人天生具有这种能力，而大多数人须要为之奋斗。程序员

使用有意义的名字

选择可以揭示意图的名字。例如，定义一个变量用来表示“上次更新的记录”，应当将它命名为 lastUpdatedRecord，而不是 record 或 lastRecord（某个文件中的最后一条记录？？）。算法
作有意义的区分。不要经过故意的拼写错误、数字后缀或噪音词后缀来区分类似的名字。例如，ProductData vs ProductInfo，ProductInfo 包含了什么 ProductData 不包含的信息吗？Data 和 Info 就是噪音词，以它们为后缀来区分不一样的名字是没有意义的。数据结构
增长有意义的上下文。变量 state 自身没有明确的意义，可是把它放到一个意义明确的类里面，别人很容易就能明白你的意图。例如 address.state 或 engine.state，app

最不济但也正确的作法，是将上下文做为名字的前缀或后缀，例如 addressState。spa

调用链中的每个部分都应当只增长新的上下文，这样能够缩短名字，同时保持其意义明确。code
使用解决方案域中的名字。代码会被程序员阅读，因此能够而且应该使用计算机科学术语、模式名、算法名、数学术语等。htm
使用问题域中的名字。若是要表达的内容与问题域联系更为紧密，那么问题域中可能有合适的名字可用。使用问题域中的名字有助于更好的了解问题域，与客户拥有共同语言，而且能够解耦问题域的概念和特定解决方案。你可使用 string address 定义一个来表达“送货地址”的变量，可是使用 Address shippingAddress 更加明确和健壮。对象
```
// instead of
String state
String streetAddress
Int houseNumber

// use
Address address
复制代码
```
不要使用缩写。使用 getWindow 而不是 getWin。

概念

命名与概念的抽象和封装行为有关。

为每个抽象概念挑选惟一的名字 并坚持使用它。让团队成员在表达同一个概念时使用相同的名字。
不要使用 双关语，不要为不一样的事物使用相同的名字。例如，有两个类，一个类使用 add() 方法建立并添加用户，另外一个类有一个方法用来往集合中插入一个参数，为每个抽象概念挑选一个名字 这一原则可能会误导你为两个方法取一样的名字 add()，事实上两个方法有不一样的语义。
避免意象映射（mental mapping）。这一点很是重要。不要让读者将名字理解为他们知道的其余东西。甚至应该为循环计数器命名，使其更容易理解。不要作一个炫耀智力的聪明程序员，要作一个清晰为王的专业程序员。

为通用操做约定统一的名字。例如，如何获取对象的 Id ?

worker.getId()
candidate.id()
employee.id.get()
supervisor()
复制代码

使用精确的对立词。若是你能够 open()，你应该也能够 close()，若是你能够 start()，你应该也能够 stop()。

噪音和样板

命名应该尽量的干净和短小。噪音让读者阅读更多的内容却没有产生任何好处，而是带来困惑。

不要制造噪音。你的 ProductInfo 什么意思？它与 ProductData 有何不一样？相似这样的后缀就是噪音。
避免注释。好的命名远胜于注释。
小心 I 开头的命名（接口陷阱）。不要经过给具体类添加一个前缀 I 的方式来得到一个接口类。IDollar 不是一个比 Currency 好的名字。Carlo Pescio 在其博文 Your coding conventions are hurting you 中详细阐述了这一观点。
不要增长没必要要的上下文。例如，不要把项目名的缩写做为前缀，这会影响 IDE 的自动补全功能，而且难以在其余项目中复用。

虚假信息

避免使用与要表达的含义以外的含义过于相关的词和缩写词。

避免在名字中使用数据类型，例如 accountList，或许有一天有人会将数据结构改成使用 hashSet，这个名字将失去意义，若是使用 accounts 就不会有这个问题。
避免在长名字中间插入有细微的差异的词。例如，使用 o 或 l，它们与 0 和 1 太过类似。
避免注释。常常会出现代码变了，注释却没有更新的状况。

人类读者

名字要有 必要的长度 以表达精确的含义，可是应当 尽量短 以增长可读性。
可读性赛过简洁性。CanScrollHorizontally 比 ScrollableX 好。
使代码像 段落和句子 同样可读，并尽量正确地使用语法。
使用 读得出来的名字，必须你能在听起来不像白痴的状况下讨论它。例如，若是变量名为 plhmbuster，你如何与别人讨论它。
不要可爱或聪明。对于一个有趣的名字，只有当知情人还在项目团队中的时候，它才是可理解的。
使用可搜索的名字 以便 IDE 可以帮到你。例如，用常量表示魔数。
避免发音类似的名字。
避免容易拼错的名字。