体面编码之命名规则

18-12-31 banq
                   

体面编码就是编写更好代码的简明指南,这是一份指南/清单,可帮助人们提高编码和代码审查。

计算机科学中只有两件事:缓存失效和命名 - 菲尔卡尔顿

每个东西都有一个名称,每个名称只用于一件事。使用多个词来表示相同的事物,或者同一个词来表示不同的事物,会浪费认知的努力并且可能导致混淆。这不仅适用于代码,而且适用于我们工作环境中的所有内容,例如:变量和类名,方法名,数据,域概念,存储库,配置和权限。

使用来自世界,商业和技术领域的知名人士。这样做可以保持一个共同的词汇表,使通信更有效率。避免使用不同的含义重载这些名称。

使用传达意义的名称。意义是能够理解代码的关键。诸如“数据”或“值”之类的通用名称信息量较少。

避免让来自其他上下文的不良/不一致的名称蔓延到代码中。这样的上下文包括遗留代码,库和我们交互的其他应用程序。建立遵守这些命名准则的边界,并保护其免受外部污染。

面向用户的名称可以与众不同。UI /输出上显示的名称通常是需求,并显示在他们自己的上下文中。如果从代码角度来看这些名称很差或不合适,请尽可能使用不同的名称。

谨慎使用首字母缩写词和缩写词。没有它们,代码通常更清晰,更容易阅读。像id一样普遍接受的是这个规则的一个例外,包括来自业务领域的规则。

避免不必要的长名称。目的不是为了传达意义所需的时间。长名称增加了对跨越多行的语句和方法调用的需求,这使得代码的可读性降低。此规则意味着避免在不必要的情况下将类型的全名用作变量/参数名称。

避免使用符合条件的名称。当已经建立了名称的上下文时,例如通过在类或方法中,没有必要重新声明该上下文。一个任务,例如,不需要taskCompleted。

对布尔值使用正名,并避免名称中的否定。否定名称会导致双重否定,这使得表达难以理解(考虑enabled: truevs. disabled: false)。使用“not”这个词有同样的问题。

避免过度使用“get”作为方法名称前缀。Getters返回值。在适当的情况下,更喜欢提供更多信息性的替代方案,例如“请求”,“获取”,“查找”,“查询”,“构建”或“创建”。

在同一背景下争取独特的名称。类似的名称很容易混淆,并且使代码难以阅读。

当有必要对每个名称进行限定时,请考虑对其进行限定。这通常产生更大的清晰度/独特性,而不仅仅是限定它以区分它,并且使得更有可能选择正确的一个用于适当的地方。示例:previousFoo&nextFoo,而不是previousFoo&foo。

考虑命名相关的东西,使它们按字母顺序一起显示。当使用字母顺序约定时,这有助于发现。例如:data,dataError,dataLoaded。

方法应该始终做他们的名字所承诺的。方法名称传达了期望,如果不满足,呼叫者将会感到惊讶。避免有条件地不做名称所承诺的事情,并且如果无法做出名称所承诺的事情则抛出异常

使用有意义的类型参数名称,其中单个字母不清楚。这提高了可读性。使用已建立的约定(例如“T”后缀)将它们与类型名称区分开来。

避免使用camelCasing复合词。它们本身就是单个单词,所以不要求它。示例:回调,密码。

拼写正确且一致。这样做有助于避免错误,并提高代码搜索能力。如果存在多个正确的拼写(例如“颜色”),请遵循平台惯例。

遵循您周围的现有惯例。这些可能是特定的方法,代码库作为一个整体,或您正在使用的技术/平台。努力保持一致性,并避免在没有充分理由的情

这个Gist可能很有用:在编程中往往有用的名称列表

banq注:名称采取英文驼峰写法!