《编写可读性代码的艺术》读书笔记 第一部分 表面层次的改进

第一部分：表面层次的改进

代码应当易于理解

代码的写法应当使别人理解它所需的时间最小化。

 

第二章  把信息装进名字中：

①  选择专业的词，并且避免使用“空洞”的词

②  避免像tmp和retval这样泛泛的名字，用描述该变量的值的名字来代替。tmp这个名字只应用于短期存在且临时性为其主要存在因素的变量。for(int i=0;i<club.size();i++)//for(intclub_i=0;club_i<club.size();club_i++)。多花几秒钟想出个好名字，你会发现你的“命名能力”很快提升。

③  在给变量、函数等元素命名时，要把他描述的更具体而不是更抽象。

④  为名字附带更多信息，加前缀或后缀：动物//危险动物。如果你的变量是一个度量的话（时间、字节数等），那么最好把名字带上它的单位，如，start_ms。附带其他重要属性（如何这是一个需要理解的关键信息，那就把它放在名字里）。

⑤  决定名字的长度：在小的作用域里可以使用短的名字；输入长名字，vi自动补齐方法：ctrl+p。经验原则：团队的新成员能否理解这个名字的含义？？丢掉没用的词，converttostring//tostring。

⑥  利用名字的格式来传递含义：有目的的使用大小写、下划线等。

 

第三章不会误解的名字

小心可能会有歧义的名字，多问自己几遍：“这个名字会被别人解读成其他的含义吗？”

推荐使用min和max来表示（包含）极限。

推荐用first和last来表示包含的范围

推荐使用begin和end来表示包含/排除范围。

给布尔值命名，像is,has,can,should这样的词，可以把布尔值变得更明确。

要小心用户对特定的期望。比如用户会期望get（）是个轻量的方法。

 

第四章审美

三条原则：①使用一致的布局，让读者很快就习惯这种风格。②相似代码看书去相似。③把相关的代码分组，形成代码块。

如果多个代码块做相似的事情，重新安排换行来保持一致和紧凑。

在需要的时候使用列对齐。

如果在一段代码中提到A/B/C，那么不要在另一段代码中说B/A/C，选择一个有意义的顺序，并始终使用这样的顺序。

用空行把代码分成逻辑上的“段落“。

一致的风格比“正确”的风格更重要。

 

第五章该写什么样的注释

注释的目的是尽量的帮助读者了解得和作者一样多。（当你写代码时，你的脑海里会有很多有价值的信息。当其他人读你的代码时，这些信息已经丢失了——他们所见的只是眼前的代码）。

1、 什么不需要注释：

a)      不要为那些从代码本身就能快速推断的事实写注释。

b)      不要为了注释而注释。

c)       不要给不好的名字加注释，摒弃“拐杖式”注释——应该把名字改好。一个好的名字比一个好的注释更重要，因为任何用到这个函数的地方都能看到它。好代码>坏代码+好注释。

2、 记录你的思想：

a)      加入“导演评论”

b)      为代码中的瑕疵写注释。TODO:（我还没有处理的事情）；FIXME:（已知的无法运行的代码）；HACK:（对一个问题不得不采用的比较粗糙的解决方案）；XXX:（危险！这里有重要的问题）。

c)       给常量加注释。常量背后的故事，为什么是这个值。

3、 站在读者的角度

a)      公布可能的陷阱

b)      “全局观”的注释

c)       总结性的注释

写注释三个步骤：①不管你心里想什么，先把他写下来。②读一下这段注释，看看有没有什么地方可以改进。③不断改进。

 

第六章写出言简意赅的注释

注释应当有很高的信息/空间率。

1、 让注释保持紧凑（能有一行就别用三行）。

2、 避免使用不明确的代词，it，this等

3、 润色粗糙的句子。

4、 精确的描述函数的行为。

5、 用输入/输出例子来说明特别的情况。Example:xxxxxx.

6、 声明代码的意图。

7、 “具名函数参数”的注释。

8、 采用信息含量高的词。Eg：canonicalize，brouteforce，naïve solution

  ------from 《the art of readable code》