0x00000007 The Art of Readable Code《编写可读代码的艺术》 阅读笔记（上）

---

写在前面的话

由于工作和学习编写代码越来越长，经常也需要对之前的代码进行维护，有一些与维护项目和编码风格相关的资料也开始读起来。并且对代码编写中的隐藏bug也开始谨慎起来。
这里先阅读: The Art of Readable Code《编写可读代码的艺术》，对编码细节部分进行关注。后面有时间也会持续跟进这一部分内容。
这些技巧和方法不能只是纸上谈兵，也需要许多的源码阅读和工程实践反复揣摩。

P.S : 最近有点忙，上周没有来得及写博客，后面继续更新MMClassification源码阅读(*/ω＼*)。

前言 + 第1章 代码应当易于理解

（作者前言建议：本书1~2周看完）

1. 可读性基本定理：
   代码的写法应当使别人理解它所需的时间最小化。
   （这里理解是指：理解该部分运行和交互逻辑，能够改动它，甚至找出缺陷和不足。）
2. 代码行数不是越少越好，应该保证理解代码所需时间最小化上，尝试缩短代码行数
3. 理解代码所需时间最小化目标和其他没有冲突，甚至有助于引向更好的架构和易于测试。（因为后面目标往往是在能够充分理解的基础上加以实行）

---

为了方便，我们使用下面的符号表达示例是否正确：

• 不正确示例
• 正确示例

第一部分 表面层次的改进

第2章 把信息装到名字里

选择一个好名字，就能够承载很多信息。
具体来说，有以下需要注意的点：

1. 选择专业的词

   • def GetPage(url): …
   • def FetchPage(url): …
   • def DownloadPage(url)…

   简单来说，找到更有表现力的词语，来精确描述该变量和函数的意义或功能。
   这里需要一定的英文能力（最好多查查字典），以下是一些推荐：
   a. 网站（能够输入中文，返回一些推荐英文命名）：https://unbug.github.io/codelf/
   b. 书中推荐的一个表格

2. 避免泛泛的名字

   • tmp, foo, retval
   • sum_squares

   关键：用一个描述变量的值的名字代替一些信息不够的命名。
   进一步讨论：
   a. tmp 相关
     当然，有些时候 tmp 类型名字足够好，比如交换两个数值(这里使用tmp仅仅表示临时存储）。
     有些时候可以把tmp加在名字中，如tmp_file，表示临时文件。使得代码逻辑更加清楚。
   b. 循环/迭代器
     一般用i , j , iter表示迭代器本身，如果多重循环内，需要同时使用坐标查找信息，i , j , k可能会导致代码较难发现问题，比如：
   
   这个时候使用精确名字，或者添加一个前缀，比如（club_i, member_i, user_i），或简化一点（ci , mi , ui）会更好。如下：
   
   c. 空泛的名字何时使用
   除非有好的理由，尽量不使用空泛的名字，如tmp , retval。

3. 用具体名字代替抽象的名字
   变量和函数命名一定要具体，而不是抽象。比如监听某一个给定的TCP/IP端口：

   • ServerCanStart()
   • CanListenOnPort()

   一个例子：–run_locally
     如果一段代码可运行在服务器上，run_locally名字会给人带来疑惑:（本来目的是输出额外调试信息，这种情况一般在本地运行，所以命名为run_locally）
   
     这个时候使用–extra_logging更好。但是如果run_locally包含更多功能，如与本地数据库做交互。这个时候更好的方式添加一个–use_local_database命令，把这两个功能分解。而不是使用一个–run_locally执行一个功能。

4. 使用前缀或后缀来给名字附带更多信息
   例如：

   • string id = “ad84”;
   • string hex_id = “ad84”;

   拓展讨论：
   a. 带单位的值

   • start_time = …;
   • start_time_ms = …;
     
     b. 附带其他重要属性
       如果变量存在意外或危险情况都应该采用这种技巧：
       比如消息在检查前命名为 untrustedMessageBody 或 unsafeMessageBody.如果检查后，应该命名为 trustedMessageBody 或safeMessageBody。下面是更多的举例：
     
     注意，不是每一个地方都加上，而是添加在容易误解地方，并且误解后导致一些异常情况（尤其是安全问题）的产生。
     
     这里是一个 link 简单介绍各种命名规范。

5. 决定名字的长度
   选择名字时，不应该太长，没人希望工作中遇到这样的名字：
   newNavigationControllerWrappingViewCOntrollerForDataSourcesofClass
     这种名字除了难记，而且显示起来不方便。
     但是一味的短也不适合，可能会丢失信息，导致代码不容易读，甚至引发误解。
     一些原则建议：
   a. 小作用域中使用短名字

   	if (debug) {
   	map<string, int> m;
   	LookUpNamesNUmbers(&m);
   	print(m);
   	}
   

   如上，虽然m没有什么信息，但是这段代码能够表明m的含义。并且m不在其他地方使用。
   b. 不要担心输入长名字——IDE单词补全
   c. 首字母缩略词和缩写
   有些时候使用缩写，比如BackEndManger -> BEManager。
   但是注意，如果整个团队，特别是团队新成员能够很好理解并接受这种缩写。那这些名字没有问题。（比如上面的缩写不是一个好建议）。
   常见的有evaluation -> eval , document -> doc, string -> str。
   d. 丢掉无用词
   ConvertToString() -> ToString()
   DoServerLoop() -> ServerLoop()

6. 利用名字的格式来表达含义
   使用下滑线，不同命名规范混合，能够把更多信息加入到代码中，例如：
   
   kMaxOpenFiles -> 常量（小驼峰命名）
   LogReader，OpenFIle ->类与函数（大驼峰命名）
   local_file -> 变量
   offerset_ -> 成员变量（相比局部变量添加一个_）
   e.其他格式规范
   

第3章 不会误解的名字

 有时可能取名会导致歧义。
 这个时候更好的建议是多想一下，这个名字会导致歧义吗？
下面是一些例子：
a. Filter()

b. Clip(text, length)


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

d. 推荐 first 和 last 表示包含范围。

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

Python 里面使用start 和 stop 来表示，如果stop 包含在范围内，一般会添加一个标志位，设定为true;
这个时候个人建议如果使用改语言，其通用风格如此。应该按照follow这种风格进行设计。
f. 给布尔值命名：

g. 命名与使用者期望匹配（不要取一些和用户先入为主概念相冲突的名字）
g.1: getxxx()


g.2: list::size()

很显然，这里是指所有设计函数和类型时候（没有特殊情况或理由），尽量和大众（之前程序员使用风格）相一致。
h. 权衡多个备选名字：
 对于某些重复配置，只是修改部分参数，其他参数和之前配置文件一致。
 配置都是使用 key-value 保存，这个时候如何选择如下备选名字

1）template 往往表示抽象事务，必须通过某种“填充”，才能表示具体。不合适
2）reuse 可能理解为“实验重复n次”，这里更加建议为 reuse_id;
3）copy 容易理解为“拷贝xx n次“，这里最好改为copy_experiement;
4） inherit 容易理解为继承后得到更多东西，这里更好使用 inherit_from 或 inherit_from_experiement_id。

第4章 审美

这里主要将如何更好的留白，对齐使得代码易读。

1. 使用一致性布局。
   

2. 让相似代码看上去相似。
   a. 重新安排换行保持一致和紧凑。
   
   （某一行代码和其他换行不一致，可以考虑添加换行，只是上面代码写了许多重复注释）
   
   b. 用方法整理不规则的东西
   
   比较杂乱的代码可以考虑使用辅助方法CheckFullName进行优化：
   
   CheckFullName内部实现如下：
   
   这种优化能够减少大量主代码的冗余；添加测试变得简单；并且使得测试用例重要部分变得直白。
   b. 在需要时候使用对齐
   
   在大量重复意义代码（或列表）中，很容易快速阅读，定位是否存在错误。
   注意 如果维持这种结构需要很多功夫，可以不这么做（比如改动一个部分，其他部分都需要改动）。

3. 相关代码进行分组，形成代码块。
   a. 选一个有意义的顺序，始终一致使用它
   很多时候，代码的一些顺序不会影响正确性，我们可以遵循一些排序方式，能够使得检查代码更加容易，比如：
   
   b. 把声明按照块组织起来
   
   一种更好的做法：
   
   
   c. 把代码分成“段落”
   
   举个例子：
   
   修改后：
   
   d. 个人风格一致性
   比如左大括号位置，if else的书写方式等。
   如果采用了一种书写规范，整个代码统一起来是很重要的。

第5章 改写什么样的注释

注释的目的是尽可能帮助读者了解的和作者一样多。

1. 了解什么不需要注释
   不要为那些可以从代码中快速推断的事实写注释
   例如下面注释都是无用的：
   
   当然，快速也是一个需要把握的度，例如下面这段代码：
   
   通过阅读代码本身，总能够理解这里的目标，但是这里给出一个注释能够更快速理解这句代码的做法。
   a. 不要为了注释而注释
   不要把函数名字或参数重写，更好的做法是补充一些细节信息：
   b. 不要给不要的名字加注释（最好把名字改好）
   两个例子：
   
   

2. 用代码记录你的思想
   在写代码过程中好的想法可以写入注释中，例如：
   a. 加入“导演评论”
   b. 为代码中的瑕疵写注释
   一些例子：
   比较流行的标记：
   
   更加重要的是应该随时把代码如何改动的想法用注释记录下来，这样给读者带来当前代码质量和状态一些见解。更好的指出代码后续优化方向。
   c. 给常量加注释
   
   有些常量不需要加注释，如SECOND_PER_DAY。
   需要加注释主要指代你在设置这个常量时候的想法。

3. 站在读者的角度，去想象他们需要知道什么
   一个通用的加注释的技巧就是：想象你的代码对于外人来讲，看起来是什么样子的。
   a. 意料之中的提问
   b. 公布可能的陷阱
   案例：
   
   c. “全局观”注释
   对于不了解整个业务逻辑代码的“新人”，应该加入类似这种注释在代码中：
   
   一个文件级别注释简单例子：
   
   d. 总结性注释
   在函数内部，对于某一些操作写出一些类似“全局观”的注释也是一个不错的注意，例如：
   
   包含几大块的长函数对于这种总结性注释尤其重要和有用。
   5. 最后的思考——克服“作者心理阻滞”
   如果感觉写出好的注释要花很多功夫，作者如果有这种“心理阻滞”，最好的方法现在开始写。
   当下次写注释犹豫不决时候，把心理活动写下来就行了，虽然这种方法可能不成熟。（个人认为：这是一个优化过程，通过不断练习才能够做得更好。）
   
   概述一下，我们将写注释改写成以下几个步骤：
   1）不管心理想什么，先把它写下来。
   2） 读一下这段注释，看看有什么地方可以改进。
   3）不断改进。

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

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

1. 让注释保持紧凑
   一个例子：
   

2. 避免使用不明确的代词
   尽量减少指代不明确的代词，如果有，填充为实词。

3. 润色粗糙的句子
   

4. 精确地描述函数的行为
   

5. 用输入\输出例子来说明特别的情况
   一个精选的例子比注释更加有用，比如：
   
   

6. 声明代码的意图
   

7. “具体函数参数”的注释
   python 语言可以通过名称形参来进行一些注释信息，如：

   Connect(timeout = 10, use_encryption = False)
   

   C++/Java可以考虑通过注释来实现，如：

   void Connect(int timeout, bool use_encryption) {...} 
   
   Connect(/*timeout_ms =*/ 10, /*use_encryption = */False);
   // 由于某些原因，timeout_ms不能作为Connect命名的参数，这种注释还能起到补充说明的作用
   

   大多数情况不需要采用这种注释，采用这种注释也是为了更加紧凑的解释难以理解的参数。

8. 采用信息含量高的词
   一些常用的模式/定式出现，可以使用这些名词代替长段术语，比如：
   
   

---

第二部分 简化循环和逻辑

第7章 把控制流变得易读

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

1. 条件语句中参数的顺序
   
   C与C++语言以前有事也会用“尤达表示法”，即if(NULL == obj)来避免不必要的错误（如 == 写成 =）。
   但是下载编译器能够对这种情况做出警报，所以这种方式很多时候是不必要的

2. if/else语句块的顺序
   很多时候if else 顺序可以互换，但是有些时候一种顺序比另一种情况更好：
   举例：
   

3. 三目运算符使用
   相对于最求最小化代码行数，一个更好的度量方法是最小化人们理解代码时间。
   默认一般使用 if else，只有情况十分简单情况下使用三目运算符。

4. 避免do/while循环
   a. do while 把一段代码是否执行条件放在后面，这是不自然的。很容易导致读者阅读两次代码块。
   幸运的是，大部分do while可以改写为while循环。
   b. do while 循环体中出现continue容易让人迷惑。
   所以尽可能不使用这种方式

5. 从函数中提前返回
   单一出口一般是为了保证调用函数结尾的清理代码，但是现代编程语言很多已经实现这种机制：
   
   所以，之前很多人认为：一段程序中出现多条return语句是有问题的 这种看法可以被抛弃掉了。
   如果是单纯C语言实现的代码，当函数退出没有任何机制触发特定代码。这时可能需要考虑谨慎使用 goto cleanup；

6. 臭名昭著的goto
   除了C语言外，其他语言不太会使用goto（主要有很多替换方案）
   多个goto使用可能会导致问题。简单一处使用goto往往不是特别大的问题（如5中多种退出代码的使用场景）

7. 最小化嵌套
   if else 内部嵌套很容易阅读起来忘记自己处理哪一种状态（如复合判断条件）下进行代码块。
   所以减少这种嵌套很有必要：
   a . 嵌套的形成：
   一般是添加需求和操作，例如：
   
   但是后来其他人遇到以上代码时候，所有修改信息都被删除，所以会导致阅读发生困难。
   一个好的建议：当对代码做出改动时，从全新的角度审视它，将其作为一个整体看待。

   b. 解决方法1：提前返回
   修改上面代码一种方法
   c. 解决方案2：减少循环内的嵌套
   
   （实际上，还能够通过合并/调整一些判断条件和对应代码块处理流程/先后顺序，优化整个代码过程，这里不进行举例了，后面章节部分会涉及到这一点，更多的建议通过阅读源码等方式去理解掌握）=>个人认为：这也是部分源码实现过程看上去和原理出入较大，导致一些迷惑的原因之一。
   当然，这种做法更多是考虑实现的简单和bug-free。原理更注重理解所导致的trade-off。

8. 你能理解执行流程吗
   在实践中 软件流动过程 可能 通过库/框架和其他的代码组织方式变得不够明显，例如：
   
   这些结构在某些时候使代码可读性变强，冗余减少。但是过分滥用会导致难以跟踪代码。

第8章 拆分超长的表达式

把超长的表达式拆分成容易理解的小块能更有助于我们阅读代码。

1. 用做解释的变量
   
2. 总结变量
   
3. 使用德摩根定理
   
4. 滥用短路逻辑
   
   对于小的看上去“智能”的代码段（例如三目运算符，assert），过度融合较多步骤会让人阅读困难。
5. 与复杂逻辑战斗（一个例子）
   
   
   
   
   a. 找到更优雅的方法：
   
6. 拆分巨大的语句
   
   （变量代替较长并且出现次数多的常量）
7. 另一种简化表达式的创意方法
   
   （这里甚至可以考虑使用一些设计模式，优化整体流程）

第9章 变量与可读性

这里主要讨论三个问题：
1）许多变量追踪动向困难。
2）变量作用域越大，追踪动向越久。
3）变量改动越频繁，难以跟踪当前值。

1. 减少变量
   减少一些不能改进可读性的变量。
   a) 没有价值的临时变量
   
   b）减少中间结果
   
   c）减少控制流变量
   

2. 缩小变量的作用域
   缩小变量作用域能够更好的跟踪变量变化情况。
   使用语言特性（如模块，类，函数，语句作用域），设定越严格的访问权限越好=> 这样可以减少阅读时候考虑变量个数。阅读更加流畅。
   
   
   其他的一些规则建议：
   a) C++中if作用域
   
   b）JavaScript中创建“私有”变量
   
   c) JavaScript全局作用域
   
   d) Python和JavaScript没有嵌套作用域
   
   
   
   d) 把定义向下移
   

3. 只写一次的变量更好
   这里指尽量让变量修改次数越少越好（最好是常量）
   这种需要大量修改代码结构（可以参考上面所说的技巧）

4. 最后的例子
   这个主要使用一个例子来展示之前讨论过的多条原则：
   
   
   

---

References:

1.博斯韦尔. 编写可读代码的艺术. 机械工业出版社, 2012.
2. https://unbug.github.io/codelf/

欢迎评论指正和补充