《The Art of Readable Code》

软件工程
软件工程

代码的写法应当使别人理解它所需的时间最小化。- 可读性基本定理

刚工作那会总喜欢追求一些代码语法糖，感觉有奇淫技巧的代码才是牛逼的。真正开始做项目后才发现代码可读性是如此重要，最近 code review 也因为一些命名问题修改过代码（英文词汇匮乏啊。。。）重新回顾下这本书，争取写出更易维护和可读性高的代码。

1.代码应当易于理解

代码的写法应当使别人理解它所需的时间最小化。（相比于仅仅减少行数来说）如果与其他理念冲突，本条优先。

2.把信息装进名字里

  • 选择专业的词语(清晰和精确)。比如 fetchPage 优于 getPage
  • 避免宽泛的名字: 避免 tmp 和 retval 这样宽泛的名字。好的名字应当描述变量的目的或者它承载的值，tmp_file 也比 tmp 好
  • 用具体的名字代替抽象的名字
  • 使用前缀或者后缀给名字附带更多信息(英语表示法，非匈牙利命名法)。比如 delay_secs, html_utf8
  • 决定名字的长度：小的作用域尽可能用短名称，否则应该包含足够的信息。缩略词（团队新成员能否理解它的含义，不能就不要用偏门的缩写）
  • 利用名字的格式表达含义：比如纯大写表示常量等，骆驼命名法表示类等，遵循一门语言的编程命名约定。在项目中保持一致的命名法

3.不会误解的名字

不要使用有歧义的名称

  • 用 max_ 和 min_ 前缀表示上限和下限；对于包含的范围用 first 和 last；对于包含/排除范围（左闭右开区间）用 begin 和 end
  • is、has、can、或 shoould 这样的词能使得 bool 值更明确，并且尽量避免用反义词汇。比如 use_ssl 好于 disable_ssl。（人脑更易于理解正向词汇）
  • 与使用者的期望匹配：比如使用 get 误让使用者以为这是轻量级操作，可以用 compute 替代

4. 审美

好的代码应该看上去『养眼』，三条原则：

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

编程的大部分时间都花在看代码上，浏览代码的速度越快，越容易使用它：

  • 重新安排换行来保持一致和紧凑
  • 提炼出『方法』整理不规则的东西
  • 在需要的时候使用『列对齐』。（有些编辑器插件能帮助你做这种事，比如 http://vimcasts.org/episodes/aligning-text-with-tabular-vim/）
  • 选择一个有意义的顺序。比如字典序、重要性等排序
  • 把声明按照块组织起来，按照逻辑分组
  • 把代码分成段落，比如按照步骤来分段
  • 一致的风格比正确的风格重要

5. 该写什么样的注释

好代码>差代码+好注释
什么时候加上：别人看不懂；代码使用的注意事项；

  • 什么不需要注释。不要拐杖式注释，试图粉饰可读性差的代码的注释。
  • 用代码记录你的思想。加入『指导性批注』；为瑕疵写注释(TODO,FIXME,HACK)；给常量加注释；
  • 站在读者的角度，去想象他们需要知道什么。
    • 别人读你代码在想为什么要这样的地方需要注释；
    • 可能的陷阱。比如代码中数据上规模以后有严重性能问题等
    • 全局观注释。类之间如何交互，数据流动，入口点在哪里等。
    • 总结性注释。帮助快速理解代码块，不用迷失在细节中

6. 写出言简意赅的注释

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

  • 让注释保持紧凑
  • 避免使用不明确的代词，用代码名称代替 it 等词语
  • 润色粗糙的句子
  • 精确描述函数的行为
  • 用输入输出例子来描述特殊的情况（更直观）
  • 声明代码的意图。很多时候注释就是告诉读者你写代码的时候怎么想的。
  • 使用具名函数。python 等语言能这么调用 f(timeout=1)
  • 采用信息量高的词语。业界常用词汇

7. 把控制流变得易读

  • 条件语句中参数的顺序。条件表达式左边的值倾向于是变化的值，右边的值倾向于常量
  • if/else 语句块的顺序。建议：先处理正常逻辑；先处理简单的情况；先处理有趣或者可疑的情况
  • 三目运算符。 相对于减少代码行数，更好的度量方法是理解它的时间。不太建议在三目运算符中使用复杂的表达式，不如 if/else 直观
  • 避免使用 do/while
  • 从函数中提前返回
  • 最小化嵌套。过多的逻辑嵌套会导致难以理解，大脑不断”入栈出栈”，增大圈复杂度
  • 通过提前返回减少嵌套
  • 你能理解程序执行的流程吗？线程、信号量（中断）、异常、匿名函数、虚方法等会让流程难以理解，不要滥用。

8. 拆分超长表达式

大多数人的大脑最多只能同时考虑 3~4 件事情，代码中的表达式越长，就越难理解。

  • 引入解释变量。
    • if line.split(':')[0].strip() == "root" 改为如下表达式:
    • username = line.split(':')[0].strip(); if username == "root"
  • 总结变量。boolean user_owns_document = (request.user.id == document.owner_id)
  • 使用德摩根律简化逻辑表达式。（口诀：分别取反，转换与/或）
    • not (a or b or c) <=> (not a) and (not b) and (not c)
    • not (a and b and c) <=> (not a) or (not b) or (not c)
  • 不要滥用短路逻辑。短路求值有时候会很简洁，但是影响可读性
  • 从逻辑的反面思考有时候能简化表达式
  • 提炼重复表达式为变量

9. 变量与可读性

变量的草率运用会让程序更难理解：

  • 变量越多，越难以跟踪他们的动向
  • 变量的作用域越大，就需要跟踪它的动向越久
  • 变量改变地越频繁，就越难以跟踪它的当前值

增强可读性的方式：

  • 减少不必要临时变量；比如它没有拆分任何复杂的表达式；没有做出更多澄清；只使用过一次等
  • 减少中间结果
  • 减少控制流变量：比如 done 标记。可以通过运用结构化编程消除
  • 缩小变量作用域：防止名称污染。让你的变量对尽量少的代码可见，减少读者同时需要思考的变量个数。
  • 把变量定义放到使用前
  • 只写一次的变量更好。常量往往不会引来麻烦。让变量在较少的地方有改动，操作它的地方越多，越难以确定它的值

10. 抽取不相关子问题

积极抽出不相关子问题，能让读代码的人关注程序的更高层次目标

  • 不相关子问题：自包含的，不知道其他程序如何使用它。
  • 纯工具代码
  • 简化已有接口
  • 不要过犹不及，太多小函数会跳转增加理解负担。

11. 一次只做一件事

使『代码』一次只做一件事所用到的流程：

  • 1.列出代码所做的所有『任务』。
  • 2.尽力把这些任务拆分到不同的函数中，或者至少是代码中的不同段落中。

对于难度的代码，尝试列出所有任务，其中一些任务可以成为单独的函数或者类，也可以成为函数中的『逻辑段落』

12. 把想法变成代码

一个简单的过程使你写出更清晰的代码:

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

13. 少写代码

  • 你不会需要它：不要提前实现不需要的功能
  • 质疑和拆分你的需求：『减少需求』和『解决更简单的问题』
  • 保持小代码库：
    • 创建越多越好的『工具』代码来减少重复代码
    • 减少无用代码或没有用到的功能
    • 让你的项目保持分开的子项目状态
    • 小心代码『重量』。程序员往往不情愿删除无用代码，因为它代表很多实际的工作量
  • 熟悉你周边的库：每个一段时间时间阅读下标准库中所有函数、模块、类型的名字，防止重复发明轮子

14. 测试与可读性

  • 测试应具有可读性，其他程序员可以舒服地改变或者增加测试。
  • 使用辅助函数隐藏不重要细节。（如构建对象）
  • 让出错消息易读。
  • 使用简单但是可以覆盖边界条件的测试值。
  • TDD: 仅在写代码的时候想着测试这件事就能帮助把代码写得更好
  • 所有解耦的方法中，最好的往往就是最容易测试的那个。

不要走得太远：

  • 为了测试牺牲真实代码的可读性
  • 着迷于 100% 的测试覆盖率
  • 让测试成为产品开发的阻碍

可读性差的代码及其测试问题和设计问题：

  • 全局变量：不同测试互相影响：难以理解函数副作用
  • 大量依赖：难以构建测试脚手架：难以重构
  • 代码不确定行为：测试古怪：难以跟踪的bug

可测试较好的代码特征：

  • 类中很少或没有内部状态：容易测试，很少检查隐藏状态：易于理解
  • 只做一件事：需要较少测试用例：模块化，少耦合
  • 依赖少：可以独立测试：可以并行开发
  • 接口简单明确：明确的行为测试；可重用高