《可读代码的艺术》读书笔记1

本文章学习自英文版书籍《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<Node>& list, int max_size) {
  while (list.size() > max_size) {
    FreeNode(list.back());
    list.pop_back();
  }
}
  • 怎么多选一?
    仔细衡量

美学

这部分大概简单说了以下几点:
1、将有逻辑地代码分块放,块内代码也要有逻辑性
2、保持代码风格的一致性
3、尽量对齐

推荐阅读更多精彩内容