本文章学习自英文版书籍《The Art of Readable Code》。
开头
- 长短都不是代码衡量的最重要的标准，最重要的是可读性
命名要言之有物（命名是最好的注释）
- 避免选用一些泛泛而谈的词，而是更加准确的词。
比如get这个词就没有多少信息，你从哪里获取信息？数据库？内存？
比如二叉树某个方法的size()，你在说树的高度，树的节点个数？叶子节点个数？更加准确的名字应该是Height() , NumNodes() , MemoryBytes()......
再比如下面这段，stop是在说暂停还是结束。
class Thread {
void Stop();
...
};
启发：命名之前真的要想想所用的词有没有歧义！！！！！
- 不要使用tmp和retVal这些泛泛而又没有什么信息量的词，用之前想下是否可以用更好的名字
精准的命名可以有时可以让我们更快地找出bug
sum_squares += v[i]; // Where's the "square" that we're summing? Bug!
但事情无绝对，像以下的情况完全使用得比较精准。
if (right < left) {
tmp = right;
right = left;
left = tmp;
}
- i,j,k用在循环循环中是OK的，但是有些情况要例外
下面这种情况很容易就用错下标，因此用( club_i , members_i , users_i ) 或者( ci , mi , ui )会好一些
for (int i = 0; i < clubs.size(); i++)
for (int j = 0; j < clubs[i].members.size(); j++)
for (int k = 0; k < users.size(); k++)
if (clubs[i].members[k] == users[j])
cout << "user[" << j << "] is in club[" << i << "]" << endl;
if (clubs[ci].members[ui] == users[mi]) # Bug! First letters don't match up.
if (clubs[ci].members[mi] == users[ui]) # OK. First letters match.
当你的变量是某测量值的时候加上单位
elapsed_ms要比elapsed好给变量加上其他一些你认为重要的属性
- 过长的变量名也是不可取的
没有人会喜欢下面的命名，太长命名别人也记不住
newNavigationControllerWrappingViewControllerForDataSourceOfClass
小范围用短的变量名，全局等大范围名字就要非常精准了
BEManager / BackEndManager哪个好？
准则：非项目组成员一来就可以看懂是什么意思吗？扔掉那些不必要的信息，从ConvertToString到ToString，从DoServeLoop到ServeLoop
不同的类型使用不同的格式，比如用全部大写来代表全局变量或者常量
“Actively scrutinize your names by asking yourself, “What other meanings could someone interpret from this name?””
容易混淆的名字
- filter() 你到底是想选哪样？
results = Database.all_objects.filter("year <= 2011")
上面这句话你显然不知道要得到的年份是否大于2011？
这种情况下最好还是用 select() 或者是 exclude()
- clip
def Clip(text, length):
...
不知道length是删掉这么多还是保留这么多，用remove或者是truncation
length的单位也是有问题，到底是字节、字符、单词的长度？max_chars等会更好
- 使用limit的时候根本就不知道有没有包含临界条件，用max和min最好
CART_TOO_BIG_LIMIT = 8
if shopping_cart.num_items() >= CART_TOO_BIG_LIMIT:
Error("Too many items in cart.")
上面这段是为了防止购物车的商品数量超过CART_TOO_BIG_LIMIT，但这里有个歧义，到底包不包括CART_TOO_BIG_LIMIT这个数量？max和min是包括在内的！！
-
表示inclusive的范围的时候用first和last而不是stop之类的
stop不知道包不包括last？？
-
表示exclusive的范围的时候用start/begin和end
注：因为end在日常中也可以表示跟last一样的意思，比如the end of book，但是我们自己默认是end就是不包括，last就是包括。
通常来说exclusive会比较容易，比如下面这段：
PrintEventsInRange("OCT 16 12:00am", "OCT 17 12:00am")
PrintEventsInRange("OCT 16 12:00am", "OCT 16 11:59:59.9999pm")
- 布尔变量命名
bool read_password = true;
上面这段可以又两个意思：
1、密码需要被读取
2、密码已经读取了
用 need_password 或者 user_is_authenticated会更加清楚一些
SpaceLeft()大概是想返回一个数字， HasSpaceLeft()大概是想返回一个布尔变量
尽量少使用反面的词汇，如不用：
bool disable_ssl = false;
而用：
bool use_ssl = true;
- 满足用户的习惯
比如使用get好像是获取某个变量的值，好像轻而易举，所以在代价比较高的地方不要使用get，这会让人觉得这代价很低。
不要 getMean() 而是 computeMean()
另外一个例子，这段代码容易让程序变得很慢，因为应用程序员不知道 list.size()是个O(n)复杂度的方法，这就让ShrinkList()变成O(n^2)复杂度的方法了，用countSize或者countElements比较好：
void ShrinkList(list& list, int max_size) {
while (list.size() > max_size) {
FreeNode(list.back());
list.pop_back();
}
}
- 怎么多选一？
仔细衡量
美学
这部分大概简单说了以下几点：
1、将有逻辑地代码分块放，块内代码也要有逻辑性
2、保持代码风格的一致性
3、尽量对齐