不会被误解的变量
用 min 和 max 表示(包含)极限
我们在给变量起名时,常常会遇到含糊不清的情况,比如:
const CART_TOO_BIG_LIMIT = 10
if (shopping_cart.num_items() >= CART_TOO_BIG_LIMIT) {
// ...
}
代码中的 CART_TOO_BIG_LIMIT 含义到底是 “小于” 还是 “小于/且包括”,
建议: 命名极限最清楚的方式是在要限制的东西前加 max_ 或 min_
const MAX_ITEMS_IN_CART = 10
用 first 和 last 表示包含的范围
示例:
print(integer_ranger(start=2,stop=4))
上面代码无法判断是 少于 还是 少于且包含
尽管 start 是合理的参数。但 stop 可以有多种解读。对于这样的包含范围,使用 first /last 更好些
用 begin 和 end 表示包含/排除范围
比如 打印 10月16 当天发生的事件,
PringEventsInRange("OCT 16 12:00am", "OCT 16 11:59:59.9999")
对于这样包含/范围典型的编程规范是使用 begin/end
布尔值命名
危险示例:
bool read_password = true;
这会有两种不同的解释:
- 我们需要读取密码
- 已经读取了密码
避免使用 “read” 这个词,用 need_pasword 或者 user_is_authenticated 这样的名字代替
通常,加上像 is、has、can 或 should 这样的词,可以使语义更明确。
尽量避免使用反义名字,如:
bool disable_ssl = false;
更简单易读的表示:
bool use_ssl = true;
与使用者的期望相匹配
有些名字之所以会产生误解是因为用户对他们的含义有先入为主的印象,即使你的本意并非如此。
这种情况下,最好放弃这样的名字。
get()*
public class StatisticsCollector {
public void addSample(double x) {...}
public double getMean() {
// 遍历所有经过的数据并同时计算中值
}
}
上面一段 Java 代码中的 getMean() 当有大量数据进来时,会产生很大的代价,但一个新人可能会随意调用它。
相反,如果重命名为 computeMean() 会让人引起注意。
如何权衡多个备选名字
当你要选一个好名字时,可能会同时考虑多个备选方案。通常你要在头脑中盘算一下每个名字的好处,然后才能得到最后的选择。
示例:
高流量网站通常会测试对一个网站的改变是否对业务有帮助,也就是我们说的「测试用例」,如下有个配置文件,有多个属性和属性值。
experiment_id: 101
desc: "increase font size to 14pt"
...
当要定义另一个用例时,你可能会拷贝和粘贴大部分属性。
假设我们希望改善这种情况,方法是让一个实验重用另一个的属性(类似于“继承”),你可能写出这样的东西:
experiment_id: 101
the_other_experiment_id_I_want_to_reuse: 100
问题是 the_other_experiment_id_I_want_to_reuse 如何命名,下面有 4 个名字供考虑:
- template
- reuse
- copy
- inherit
所有名字对我们来说都有意义,但对于新成员来说,是否能快速理解它的含义?
当使用template 时
experiment_id: 101
template: 100
...
不太清楚“我是一个模版”还是“我在用一个模版”,而且模版具有抽象意义,会让人认为这不是一个“真正的”测试
当使用 reuse 时
experiment_id: 101
reuse: 100
...
会让人以为“这个实验最多可以重用100次”,如果改成 reuse_id,也会产生“重用的 id 是100”的错觉
考虑下 copy
experiment_id: 101
copy: 100
...
会产生“拷贝这个实验100次”或者“什么东西的第100个拷贝”, 如果改成 copy_experiement ,可能会好些
当使用 inherit 时
experiment_id: 101
inherit: 100
...
inherit (继承) 这个词比较符合大多数程序员的直觉,而且继承之后一般都会有修改,但要明确它是继承自一个实验,可以使用 inherit_from 甚至 inherit_from_experiement_id
综上, copy_experiment 和 inherit_from_experiement_id 是最好的名字.
对发生的事情描述清楚,且不容易误解。
总结
不会误解的名字是最好的名字——阅读你代码的人应该理解你的本意并且不会有其他的理解。在你决定使用一个名字之前,应该吹毛求疵的想下你的名字会被误解成什么。