编写可读代码的艺术笔记

标签：编写可读代码的艺术   编程规范   

第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：可测试性较好地代码的特征，以及它所产生的优秀设计

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

编写可读代码的艺术笔记

标签：编写可读代码的艺术   编程规范   

原文地址：http://blog.csdn.net/usstmes318/article/details/44784235