读代码还是读文档

Jeff Atwood说过: “Code Tells You How, Comments Tell You Why". 扩展一下:

• 代码 => What, How & Details
• 文档/书 => What, How & Why

代码并不会告诉你Why, 看代码只能靠猜测活推导来估计Why, 是揣测不准确的. 而且, 我们每个人都知道, Why是能让人一通百通的东西, 也是能够让人醍醐灌顶的东西.

但是, 代码能告诉你细节, 这是书和文档不能给你的. 细节是魔鬼, 细节决定成败.

书和文档是人对人说的话, 代码是人对机器说的话.

1. 如果你想知道人为什么要这么搞, 那么你应该去看书(像Effective C++、 Code Complete、Design Pattern. Thinking in Java等), 看文担.
2. 如果你想要知道让机器干了什么? 那你应该看代码!

因此, 认为都比较重要, 关键看你的目的是什么了?

• 如果你想了解一种思想, 一种方法, 一种原理, 一种思路, 一种经验, 恐怕, 读书和读文档会更有效率一些.
• 如果你想了解的就是具体细节, 比如某协程的实现, 某个模块的性能, 某个算法的实现, 那么你还是要去读代码, 因为代码中会有更具体的处理细节.

以下几种现象, 可以自己比较一下.

• 很多时候, 我们去读代码, 是因为没有文档, 或是文档写得太差.
• 很多时候, 在Google、Stack Overflow, GitHub过后, 你会发现, 你掌握的知识是一块一块的碎片, 既不系统, 也不结构, 更别说融会贯通. 你会觉得自己需要好好读一本书, 系统地掌握知识. 你的这种感觉一定很强烈.
• 很多时候, 看到一个算法或是一个设计时, 会想去看一下这个算法的实现代码是什么样的? 思考一下如何才能实现得好?
• 很多时候, 当你写代码的时候, 你能感觉得到自己写的代码有点别扭, 怎么写都别扭, 这个时候, 你也会有想去看别人的代码时怎么实现的冲动.

我们来分析一下看代码和看书这两个活动. 人对新事物的学习过程基本都是从“感性认识”到“理性认识”的.

• 如果你是个新手, 那应该多读代码, 多动手写代码. 因为你需要的是“感性认识”.
• 如果你是个老手, 你有多年的”感性认识“了, 那么你的成长需要更多的”理性认识“. 因为这个阶段, 一方面, 你会不满足做出来, 你会想去做更牛更漂亮的东西; 另一方面, 你知道的越多, 你的问题也越多, 你迫切地需要知道Why? 这时, 你需要大量地找牛人交流(读牛人的书, 是一种特殊的人与人的交流), 所以, 这个阶段, 你会喜欢读好的书和文章.

如何阅读源代码

首先, 在阅读代码之前, 我建议你需要有下面的这些前提再去阅读代码, 这样你读起代码来会很顺畅.

1. 基础知识. 相关的语言和基础技术的知识.
2. 软件功能. 你先要知道这个软件完成的是什么样的功能, 有哪些特性, 哪些配置项. 要先读一遍用户手册, 然后让软件跑起来, 自己先用一下感受一下.
3. 相关文档.
4. 代码的组织结构.也就是代码目录中每个目录是什么样的功能, 每个文档是干什么的.

接下来, 你要了解这个软件的代码是由哪些部分组成的.

1. 接口抽象定义. 其描述了代码需要处理的数据结构或业务实体, 以及它们之间的关系, 理清楚这些关系是非常重要的.
2. 模块粘合层. 我们的代码有很多都是用来粘合代码的, 比如中间件、Promises模式、回调、代理委托、依赖注入等. 这些代码模块间的粘合技术是非常重要的, 因为它们会把本来平铺直叙的代码给分裂开, 让你不容易看明白它们的关系.
3. 业务流程. 这是代码运行的过程. 一开始, 我们不要进入细节, 需要在高层搞清楚整个业务的流程. 这个流程中, 数据是怎么被传递和处理的. 一般来说, 我们需要画流程图或者时序处理图.
4. 具体实现
   • 代码逻辑. 业务流程和控制逻辑
   • 出错处理
   • 数据处理
   • 重要的算法
   • 底层交互
5. 运行时调试. 让代码运行起来, 用日志、debug设置断点, 实际看一下代码的运行过程, 是了解代码的一种很好的方式.

总结来说, 阅读代码的方法如下:

• 一般采用自顶向下, 从总体到细节的读法
• 画图是必要的, 程序流程图, 调用时序图, 模块组织图..
• 代码逻辑归一下嘞, 排除杂音, 主要逻辑才会更清楚.
• debug跟踪一下代码是了解代码在执行中发生了什么的最好方式

此文章为3月Day26习笔记, 内容来源于极客时间《左耳听风》, 强烈推荐该课