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

有意义的命名

1. 名副其实

• 变量、函数或类的名称应该能够准确地说明它的意义，比如它存在的意义，它做什么事，以及它应该怎么用。

• 一旦发现好的命名，就应该换掉旧的名称（当然要确定修改的难易程度）。

2. 避免误导

• 避免使用与本意相悖的词语，例如变量名 userList，如果不是 List 类型的变量，就不应该用这种命名。

• 提防使用区别很小的名称，因为很容易拼写错误。

• 避免使用误导性比较大的字母，例如 0，O，1，l，因为变量之间的区别只是这些字母的话，看错的可能性比较高。

3. 做有意义的区分

• 名称不同，那么其意义应该也不同才对。

• 不要使用数字序列作为名称的区分，会让人搞不清楚用途，例如 a1，a2。

• 多余的废话是冗余的区分，例如 getProduct 和 getProductData 这种就让人比较疑惑，意思区别不大。

4. 使用可读性好的名称

• 名称中的单词应该是可读的词语，或者公认的常见缩写，不要自造词语，例如 modymdhms 和 modifinationTimestamp。

5. 使用可搜索的名称

• 名称长短应该与其作用域大小相对应，长名称要优于短名称。

• 单字母名字应仅用于短方法中的本地变量，例如 i，j。

• 对于在代码中多次使用的变量或者常量，应该为其定义便于搜索的名称。例如数字常量 7，可以在代码中定义为 DAYS_PER_WEEK，这会比 7 好找得多。

6. 避免使用编码

• 不要添加成员前缀（或后缀），例如类成员 m_name 和 name，前后缀是以前旧代码所使用的，现在已经废弃了。

• 不要使用前导字母 I 来编码区分接口和实现，使用 impl 来标识实现类或许更好。

7. 别用俗语

• 不要使用俗语或典故作为名称，因为别人有可能不了解这方面的知识。

8. 每个概念对应一个词

• 给每个抽象概念都选定一个词，并且一以贯之。例如获取这个概念，fetch，get，retrieve 等都可以拿来使用，但是不要在代码中混杂着写，这里用 fetch，那边用 get，除非有明确说明，否则这很容易会让人受到误导。

9. 别用双关语

• 避免将同一单词用于不用的目的。例如 add 方法，在这个类中用来表示将两个数加起来，而在另一个类中则表示将对象放入集合中。因此可以修改第二个方法名称为 append 来作出区分。

10. 添加有意义的语境

• 如果语境不够清晰，可以为变量加上前缀。假如成员变量 state 在当前上下文中不是很明确时，因为 state 有可能在多个类中都存在。因此可以为其加上前缀 addrState，这样就能表明 state 是属于 Address 类了。

• 不要添加没用的语境。例如为每个名称都加上 app 的前缀，如 appUser，appAddress，这根本就是毫无意义的冗余。