编写可读代码的艺术笔记

摘要: 表面层次上的改进
命名、注释以及审美——可以用于代码库每一行的小提示。
简化循环和逻辑
在程序中定义循环、逻辑和变量，从而使得代码更容易理解。
重新组织你的代码
在更高层次上组织大的代码块以及在功能层次上解决问题的方法。
精选话题
把"易于理解"的思想应用于测试以及大数据结构代码的例子。

编写可读代码的艺术
表面层次上的改进
命名、注释以及审美——可以用于代码库每一行的小提示。
简化循环和逻辑
在程序中定义循环、逻辑和变量，从而使得代码更容易理解。
重新组织你的代码
在更高层次上组织大的代码块以及在功能层次上解决问题的方法。
精选话题
把"易于理解"的思想应用于测试以及大数据结构代码的例子。

第1章：代码应当易于理解

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

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

第2章：把信息装到名字里

1.使用专业的单词。

2.避免空泛的名字。

3.使用具体的名字来更细致地描述事物。

4.给变量名带上重要的细节。

5.为作用域大的名字采用更长的名字。

6.有目的地使用大小写、下划线等。例如，在类成员变量后面加上“_”来区分局部变量。

第3章：不会误解的名字

1.要多问自己几遍：“这个名字会被别人解读成其他的含义吗？”要仔细审视这个名字。2.命名极限最清楚的方式是要在限制的东西前面加上max_或者min_。3.当为布尔值命名时，使用is和has这样的词来明确表示它是个布尔值。4.要小心用户对特定词的期望。例如，用户期望get( )或者size( )是轻量的方法。

第4章：审美

1.使用一致的布局，让读者很快就习惯这种风格。2.让相似的代码看上去相似。3.把相关的代码行分组，形成代码块。

第5章：该写什么样的注释

1.注释的目的是尽量帮助读者了解得和作者一样多。

2.什么地方不需要注释：

能从代码本身中迅速地推断的事实。

用来粉饰烂代码的“拐杖式注释”——应该把代码改好。

3.你应该记录下来的想法包括：

对于为什么代码携程这样而不是那样的内在理由（“指导性批注”）。

代码中缺陷，使用像TODO:或者XXX:这样的标记。

常量背后的故事，为什么是这个值。

4.站在读者的立场上思考：

预料到代码中哪些部分会让读者说：“啊？”并且给它们加上注释。

为普通读者意料之外的行为加上注释。

在文件/类的级别上使用“全局观”注释所有的部分是如何一起工作的。

用注释来总结代码块，使读者不致迷失在细节中。

第6章：写出言简意赅的注释

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

2.尽量精确地描述函数的行为。

3.在注释中用精心挑选的输入/输出例子进行说明。

4.声明代码的高层次意图，而非明显的细节。

5.用嵌入的注释（如Function(/*arg =*/...)）来解释难以理解的函数参数。

6.用含义丰富的词来使注释简洁。

第二部分：简化循环和逻辑

第7章：把控制流变得易读

1.把条件、循环以及其他队控制流的改变做得越“自然”越好。运用一种方式使读者不用停下来重读你的代码。

2.相对于追求最小化代码行数，一个更好的度量方法是最小化人们理解它所需的时间。

3.当你对代码做改动时，从全新的角度审视它，把它作为一个整体来看待。

4.嵌套的代码块需更加集中精力去理解。

第8章：拆分超长的表达式

1.把你的超长表达式拆分成更容易理解的小块。2.要小心“智能”的小代码段——它们往往在以后会让别人读起来感到困惑。3.帮助读者识别代码中的主要概念。

第9章：变量与可读性

1.减少变量，即那些妨碍的变量。2.减小每个变量的作用域，越小越好。3.只写一次的变量更好。（const、final、常量）使得代码更容易理解。

第三部分：重新组织代码

第10章：抽取不相关的子问题

1.看看某个函数或代码块，问问自己：这段代码高层次的目标是什么？

2.对于每一行代码，问一下：它是直接为了目标而工作吗？

3.如果足够的行数在解决不相关的子问题，抽取代码到独立的函数中。

把一般代码和专有代码分开：它使程序员关注小而定义良好的问题，这些问题已经同项目的其他部分脱离。

第11章：一次只做一件事

1.列出代码所做的所有“任务”。2.尽量把这件任务拆分到不同的函数中，或者至少是代码中不同的段落中。

第12章：把想法变成代码

如果你不能把一件事解释给你祖母听的话，说明你还没有真正理解它。——阿尔伯特·爱因斯坦

编写更清晰的代码：1.像对着一个同事一样用自然语言描述代码要做什么。2.注意描述中所用的关键词和短语。3.写出与描述所匹配的代码。

第13章：少写代码

1.从项目中消除不必要的功能，不要过度设计。2.重新考虑需求，解决版本最简单的问题，只要能完成工作就行。3.经常性地通读标准库的整个API，保持对它们的熟悉程度。

第四部分：精选话题

第14章：测试与可读性

1.每个测试的最高一层应该越简明越好。最好每个测试的输入/输出可以用一行代码来描述。

2.如果测试失败了，它所发出的错误消息应该能让你容易跟踪并修正这个bug。

3.使用最简单的并且能够完整运用代码的测试输入。

4.给测试函数一个有完整描述性地名字，以使每个测试所测到的东西很明确。例如：Test_<FunctionName>_<Situation>这样的名字。

表1：可测试性差的代码特征，以及它所带来的设计问题

特征	可测试性的问题	设计问题
使用全局变量	对于每个测试都要重置所有的全局变量（否则，不同的测试之间会互相影响）	很难理解哪些函数有什么副作用。没办法独立考虑每个函数，要考虑整个程序才能理解是不是所有的代码都能工作
对外部组件有大量依赖的代码	很难给它写出任何测试，因为要先搭起太多的脚手架。写测试会标胶无趣，因此人们会避免写测试	系统会更可能因某一依赖失败而失败。对于改动来讲很难知道产生什么样的影响。很难重构类。系统会有更多的失败模式，并且要考虑更多恢复路径
代码有不确定的行为	测试会很古怪，而且不可靠。经常失败的测试最终会被忽略	这种程序更可能会有条件竞争或者其他难以重现的bug。这种程序很难推理。产品中的bug很难跟踪和改正

表2：可测试性较好地代码的特征，以及它所产生的优秀设计

特征	对可测试性的好处	对设计的好处
类中只有很少或者没有内部状态	很容易写出测试，因为要测试一个方法只要较少的设置，并且有较少的隐藏状态需要检查	有较少状态的类更简单，更容易理解
类/函数只做一件事	要测试它只需要较少的测试用例	较少/较简单的组件更加模块化，并且一般来讲系统有更少的耦合
每个类对别的类的依赖很少;低耦合	每个类可以独立地测试（比对个类一起测试容易得多）	系统可以并行开发。可以很容易修改或者删除类，而不会影响系统其他部分
函数的接口简单，定义明确	有明确的行为可以测试。测试简单接口所需要的工作量较少	接口更容易让程序员学习，并且重用的可能性更大