Pocket Readings

个人阅读清单记录博客

0%

如何阅读一份代码?

微信号 programmer_life 功能介绍 十年漫漫程序人生,打



Tags: engineering



via Pocket https://ift.tt/3vvYpVg original site



June 16, 2021 at 05:03PM

Comments


from: github-actions[bot] on: 6/16/2021

如何阅读一份代码? by 程序人生

2017-04-07
上文谈到了像读书一样阅读源码的重要性,今天谈谈如何阅读一份代码。我所谓的一份代码,其范围可能从几千行到数万行,有时甚至可多达数十万行。这些代码作为一个有机体,共同完成某些重要的功能。比如说几个著名的 full fledged web framework,祖师爷 rails,师叔 django 和小师妹 phoenix:

三者对比很有意思 - rails / django 的代码数都在 200k 上下,而 phoenix 小了整整一个数量级,仅仅在 20k 左右。实现大致相同的功能,语言的表现力难道差距如此之大?这解释不通。实际上 phoenix 实现的功能,和 rails 对标,应该是 actionpack/actionview 两者加起来约 80k 的代码。而 rails 内嵌的 activemodel/activerecord 应该对标 elixir 的 ecto,恰巧又是 80k 比 20k。这种差异反映了语言表现力的差异,同时也体现了框架的成熟度的区别。

几十 k 体量的代码,就像一本不薄不厚的书,读着既不算太过吃力,也不至于读完意犹未尽。

有些巨型的代码库,如 linux kernel,块头堪比『战争与和平』,代码的规模宏伟到令人绝望,大大超过了我们能够阅读理解的范围。其结果是我们每每下定决心阅读,投入的巨大的精力,却像往一池湖水里投个石子,虽掀起一丝涟漪,但湖面很快就归于平静。

读不下来,我们也不要太绝望,可以分而治之,先定个小目标,每次读一部分,比如 scheduler(20k)或者 memory management(80k)。

在选定合理的代码规模和要阅读的源码后,我们就可以清开书桌,摆上 mac,准备好笔墨纸砚,留出至少一个小时到半天时间,开始徜徉在代码的海洋。

由于上一篇文章(为什么我们要阅读源码?)从头至尾将阅读书籍和阅读代码进行对比,很多人会不禁联想本文会否和『如何阅读一本书』进行类比,提供同样的思路:基础阅读,检视阅读,分析阅读,对比阅读。不错,这些读书的方法对读代码非常有参考价值,比如说检视阅读,我们读大型代码项目,也是类似的思路:

  • 我们会读根目录下的 readme,或者任何看上去撩拨着你让你戳它的文件。这就跟书本的「序」一样,能够帮你更进一步了解这份代码的意图;

  • 接下里我们目光需要聚焦在代码的目录结构,和每个源码的文件名。他们就像书本的目录页。如果每个目录下有 readme,也可快速阅读之。很多语言和框架,有约定俗成的目录结构(Convention by Contract),因此,通过目录我们就可以快速知道哪些是可以略过的部分,比如 django 的 management/commands 目录,elixir 的 mix/tasks 目录,这些目录,承载着支线剧情,需要的时候,或者闲得无聊时再读也不迟;

  • 然后我们开始从入口梳理主线。不同语言和框架的主线不太一样,比如 C 的入口是 main(),erlang/elixir otp app 的入口是 app:start,nodejs 往往是根目录下的 index.js,等等。一般而言,application 的主线比较清晰,一路下来,会走到一个 mainloop,而 framework 的主线会晦涩一些,因为 framework 往往是 application 抽象出来的部分。

但本文不会过多这样去对比 —— 大家真有兴趣,何不亲自读读那本书(读过的请带着读代码的角度再读一遍)呢?毕竟,它更加完备,更加系统。

我想通过另一个角度 —— 阅读的场景来谈谈如何阅读。谈到场景,很多人会联想到一本著名的书:Linux 内核场景分析。该书的作者显然把握了阅读代码的实质:循着一条线索,进行端到端的一个自成体系的内容的阅读。不同场景下,我们已知的信息,未知的信息,通过阅读想要达到的目标是不一样的,显然,方法也不尽相同。这就和读书一样:想要让自己明智,读史;想要让自己灵秀,读诗;想要让自己周密,研习数学;想要让自己深刻,攻读哲学等等。

接下来,本文就从若干阅读代码的场景开始,讨论个人的读代码的一点微不足道的心得。

场景一:为了破案而阅读代码

这是我们最主要的阅读代码的场景。工作中,免不了用各种各样的开源系统(别人的代码)。使用的过程中,你会遇到各种奇葩的问题,这些问题可能源于对文档的理解不够,或者从网上抄一个已有的,并不完全适合你使用场景的样例,或者是真的撞上了八阿哥。在想方设法解决的过程中,如果同事帮不上忙,google/stackoverflow 不够给力,论坛上各种「急,在线等」也无人理会,你会开始抓狂,仿佛被摄魂怪缠上了一般,生活中的各种美好,希望,都开始离你远去。

这时,你不得不像 CSI 中的警探一样,顺着一点蛛丝马迹,开始剖析代码,试图从迷雾中还原真相。你会抛开一切纷扰和杂音,集中精力,带着线索,循着问题,读且只读和解决问题直接相关的代码。这种状态,我管它叫「猎手模式」—— 我们有如非洲草原上追逐离群斑马的狮子,把身上燃起的小宇宙集中于一点,眼睛紧盯猎物奔走的方向,腿如疾风,势如闪电,心中不断地盘算着雷霆一击究竟用锁喉,打脸抑或拉后腿胜算更大。道路上的石子划了脚,痛;飞奔时撞上了幺蛾子,烦,但这都不是事儿。就算远远的乞力马扎罗山上难得地挂上了两道彩虹,煞是美丽,自拍后发朋友圈定能破百赞,你也无暇顾及这些并不重要的细节。

专注,集中力量攻击且仅攻击一点是这样场景下阅读代码的主要方式。

拿我遇到的 nginx cache 的问题来举个栗子。一年前,当我接手 Tubi TV 的性能较低且很难维护的 API 系统后,虽打定主意日后重写,但摆在面前的,刻不容缓的问题是提高性能。应用层可以施展的空间不大(数据已经在 redis 里),所以只能在 web 层打主意。在 HAProxy 和 nginx cache 之间,我选择了后者, 因为 nginx 已经在当时的生产环境下大量使用。我虽然没用过 nginx cache,但启用 nginx cache 并不是难事,照着文档设置好 cache 的路径和大小等参数后,在需要使用 cache 的 location 下,设置 cache key 并使能即可,我本地的简单的测试运行正常。然而,在生产环境中,本该命中的请求却一直处在 miss 的状态。我一筹莫展,尝试了网上搜到的各种方案无果。最终,我决定自己编译一个打开 DEBUG 开关的 nginx 版本(--with-debug),记录更多的日志,然后对着源码找问题。

nginx cache 及 upstream 里和 cache 相关的代码量并不算多,几千行,我快速过了一下,然后就着日志上的内容寻找相关的处理流程,并在几个大的 bailout 分支猜想可能出现的情景。由于 nginx debug log 还是不够详细到满足我的需求,我在这些没有被顾及到的分支上各自加了调试代码,重新编译,运行。

这个过程中,「猜」起到了很大的作用。我记得本科时的数学老师 —— 一个可爱的小老头 —— 点名提问对方答不上来时,常常挂在嘴边的口头禅是:你猜一下嘛。他总说连蒙带猜也是解题的一种思路,伟大的数学家同时也是伟大的猜想家。

我们读代码时,猜文件名,函数名,变量名的意图,猜某个分支的意图,猜某段代码的意图,最终结合运行的结果,打印出来的调试信息来印证我们的猜测。这是读者和作者间有趣的猫鼠游戏。读得越多,猜得越多,印证得越多,形成一个有效的 feedback loop(read - guess - verify),你下次猜测成功的几率就越大。

最终,问题被我定位出来 —— 它是两三处 configuration 未正确配置的问题。stackoverflow 上的答案是部分正确的,它解决了绝大多数人的问题 —— 没有 ignore cache control 相关的 header 几乎被每个初次使用者忽略了,它也是我的配置问题之一。但之所以这个答案没能解决我的问题,是因为我们生产环境中的 nginx 有个不起眼的配置 disable 了 proxy buffer,从而导致 nginx 直接跳过 cache。

从以上的过程中,我们抽象一下,看看为了破案而阅读代码要注意什么:

  1. 带着线索,从一堆代码中找出和问题相关的代码。nginx cache 的例子中,线索是 proxy 的 upstream,cache 总不能命中,所以出问题的代码和 cache,proxy,upstream 有关。源码目录里一翻,就能挑出需要看的文件。由于问题在 cache 上,在挑出的文件中,具体看 cache 相关的函数名,宏名,以及代码。

  2. 专注阅读挑出来的内容,忽略不相干的噪音。在阅读的过程中,着力寻找潜在的触发问题的路径,然后动用「我猜我猜我猜猜猜」大法,加调试信息。

  3. 编译运行修改过的代码,复现问题,分析调试信息,然后,bingo,恭喜你答对了!请进入第 5 步。

  4. 没答对,请回第 1 步。别急,这不是高考,在老板忍无可忍炒你鱿鱼之前,你一直拥有再来一瓶的机会。

还有个关键的第 5 步,我单拎出来说。很多时候我们轮回数次,终于在第三步 bingo 后快乐地像是刚刚 K.O. 了对手的春丽,夹着腿跳将起来,左右手在空中一齐比划着二,得意忘形,以至于忘记了执行第 5 步。

喜悦是短暂的,记忆也是短暂的。整个过程你的目标是如此清晰,执行力无比强大,为达到目的「不择手段」。三天后老板问你,小程啊,你很棒啊。你用了什么手段征服了这个无比难缠的八阿哥?这时你拼命追忆,却像拿筛子盛水,忙乱半天一无所获。你开始怀疑人生:三天前的我和现在的我究竟是不是一个人?

所以关键的第 5 步是:复盘。解决问题后,别着急接受同事们的致谢和女(男)神的秋波。趁着那坨记忆还热气腾腾,抄起 evernote(或者 xxx),把整个过程用最简洁的方式记录下来 —— 关键代码,关键路径,到达终点的整个猜测过程,以及那些日志验证了猜测是对的,哪些日志验证了猜测走不通(恭喜你 —— console 或者 terminal 在这个时候应该还没关),总之,你在不择手段的过程中用过的一切手段,都应该像记流水账一样记录下来。最后分析总结:

  • 这个问题的 root cause 是什么?触发它的代码的流程是什么?

  • 在读代码的过程中,哪些地方我猜对了,哪些没猜对?

  • 有功夫的话,代码的哪个部分是值得细细品读把玩的?

  • 下次再出现类似的问题,我该怎么更快地从源码中定位出问题?

在这种「破案」般阅读代码的历程中,如果没有复盘,你 70% 的功夫白费了 —— 你花了不少时间,读了不少代码,除了一个好的结果外,并无太大的收获。可惜的是,绝大多数工作场景,我们都略过了这步。我自己也是(深刻检讨中)。写这个章节时,我搜了搜我的 evernote,翻了翻我的邮件,除了去年初有封邮件只言片语介绍了我使能了 nginx cache 外,再无其他记录。好在我当时解决完问题顺便又读了些 nginx cache 的代码,有些许印象,所以还能把它搬出来做例子。

复盘帮你把这样的信息沉淀下来,让你有机会回顾,进而组织和固化成上篇文章中所说的知识。这样的内容累积多了,慢慢你的头上就会顶起一个光环,光环上傲娇地写着:砖家。

场景二:为了明理而阅读代码

场景一所述的读代码方法是被动的,为了对付问题而读,是大部分人精进代码的唯一途径。这就好比英雄无敌里你就做个守成之主,收收矿,屯屯兵,从不主动招惹野怪,只等着敌人来进攻。这样三个月下来,就打了几仗,稳则稳矣,无奈经验值增长太慢。

要想涨快点怎么办?主动出击啊!计算机领域的很多算法,基础知识,理论,在看过书,读过文章后我们都似懂非懂,这时,阅读代码就是最快地巩固和加深理解的方式:

  • 算法:bloom filter 究竟怎么实现的?怎么样把 bandit 算法在自己的系统上做简单的推荐?ossip 协议实际的生产环境的代码是什么样子的?Linux kernel 如何实现 O(1) scheduler?

  • 基础知识:一个完整的涵盖 HTTP 1.1 协议的 REST API framework 如何实现?一个 packet 从 OS 的 driver 是如何一路送上 application 的?什么是 zero copy?Linux kernel 如何实现 zero copy?

  • 理论:啥是 IoC / DI / Pub Sub?各种 framework 都是咋实现这些设计模式的?supervisor 这个 behavior 背后的实现是如何的?

这个过程是一个正反馈,是马太效应累积地过程。你读的书多,你脑子里的知识点就多,疑问同样也多。这些疑问促使你读相关的代码去印证和解惑,代码读多了,又感觉理论知识欠缺,于是周而复始,不断学习下去。反之,书读得少,你脑子里都没存几个问号,也就无所谓读代码去求证了。

以 REST API framework 为例 —— 两年前我还在 Juniper 做 web security 时,需要做一个坚实的 API system。我们知道做网络的,干起事来要比做互联网严谨得多(所以也慢得多),于是我花了好些时间读了 RFC 2616 及其后续的修订(7230-7235)。然后就是对 API framework 进行选型,找个合适的。当时我正好在研究 clojure,便拿了 liberator 来看。Liberator 受 erlang 下的 webmachine 启发,用简单的 macro 把 decision tree 实现得很优雅。后来我又扫了下 webmachine 的 decision tree,pattern matching + 递归,非常漂亮。可惜当时我在的团队思想比较僵化,眼里只容得下 python。无奈我退而求其次,选用了 eve,一个 python 下的 rest API framework。eve 的代码质量中规中矩,平铺直叙,明显像是你我写出的代码的模样。

详细讲讲我读 webmachine 的过程。我读 webmachine,完全是 liberator 的引荐,liberator 的作者说其 decision tree 来自于 webmachine,并附了图。这时的我就像刚练了李小龙的截拳道,听闻这功夫源自咏春,一下子就心痒痒欲探探咏春的虚实了。

webmachine 的代码很短,只有 4700 行。循着文件名很快就能找到 webmachine_decision_core.erl,这是要阅读的主体内容,约 800 行。这 800 行代码,我们可以将其分成三个部分:头 150 行,decision tree 的架子;中间 300 多行,是具体的一个个 decision 的实现;剩下的两百行,是辅助函数。

每个 decision 的流转见下图(https://raw.githubusercontent.com/wiki/webmachine/webmachine/images/http-headers-status-v3.png):

(不要费力打了,这图微信里没法看)

这里 atom 的命名完全跟着图走,比方说 v3b13 这个 atom,含义是 v3 版本的图,b 列 13 行的 decision node。这是第一个 decision,如果 service available,则整个 flow 继续往下走,否则返回 503 service unavailable。

明白了这一点,按图索骥,代码的执行流程非常好懂。接下来的事情就很简单了 —— 顺着流程一个一个看 decision node 的代码,RFC 2616 变得鲜活起来,在你眼前跳动。我们再看一个例子:precondition check,是 v3g11:

这段代码从 http header 里读出 if-match header 里的 etags 列表,然后通过 resource_call 调用 generate_etag,来生成 etag,和 etags 里的任意一项匹配,如果匹配,跳转到 v3h10,否则 412 preconditional failed。webmachine 怎么知道如何生成 etag 呢?这便是 framework 的功力了,它抽取并实现协议的公共的部分,而将业务逻辑延递给使用 framework 的 application。换句话说,generate_etag 是 application 要实现的 callback。这便是 IoC。

这个代码解释到这里,明白 HTTP 协议中 etag 作用的人,或者对 concurrency control 方案清楚的人自然一目了然;但我相信不少人会很难理解它的应用场景。再进一步解释一下:比如小明和小红是程序人生的两个管理员,他们通过 API 同时从数据库中获取到程序人生的基本信息(名称,描述等) v1。小明把程序人生的名字改成了「序员人生」,调用 PUT API 成功修改数据为 v2。小红也同时修改这个数据,但她还是使用原有的 v1 的数据进行修改,结果提交时把小明的修改覆盖了。这是个 concurrency control 的经典场景 —— 令人谈虎色变的 race condition。怎么办(想想你平时怎么处理)?HTTP 协议的处理办法是:小明和小红拿数据的时候,同时拿到一个「版本号」(你就想象成数据的 sha1),这里管它叫 etag。小明更改后,数据的 etag 变了,小红拿旧的 etag 提交时,服务器一检查当前的 etag,不匹配,于是便 412 了。这是一个简化了的 optimistic lock。

拉拉杂杂说这么多,只想说明一件事:能够读懂代码,和理解代码的应用场景是两码事。但是当你真正理解之后,你的代码功力就大涨。日后做并发环境下的共享对象更新,你脑袋里会闪个问号:吓,这里可不可以不用 lock(pessimistic lock),而是考虑类似 If-Match 的机制呢?

言归正传。之前的整个过程,我都在理解作者的意图。心满意足后,我一般会问问:

  • 这代码有可以优化的地方么?

  • 有潜在的安全漏洞么?

  • 是否有未处理的状态或者异常?

这短短五行的代码,lists:member 是个 O(N) 的操作。O(N) 的操作都该引起我们的注意。我们知道,membership check 用 set 而非 list,效果更佳。从安全的角度讲,split 出来的 ETags 是个薄弱环节。攻击者可以构造足够大且复杂的 if-match 头,来扯慢单个 request 的处理,从而达到更好的 DoS 效果。至于未处理的状态,这里可以放心 —— 有了上文中所示的如此详尽的流程图(状态机),这代码不会有大的问题。

OK,这栗子炒的时间够长了,打住。我们对比一下三个 API framework 的代码量:liberator 1.2k,webmachine 5k,eve 12k。读 liberator 的感觉像是楚辞,优美但晦涩;读 webmachine 的感觉像是数学教材,满纸都是递归推导;读 eve 的感觉像是读本科生的论文,完成了功能而已,读完没啥印象,倒是有些反面教材:整个 framework 写得太死,一些本不该 framework 做的决策被做了,以至于要满足我们的某些需求,最终只能通过 fork 它改 framework 的代码来完成,而这是 framework 的大忌(我们当时用的是 0.4,写本文时是 0.7)。

我们总结一下 —— 为了明理而阅读代码的方法并不太难:

  1. 先使用前面所述的检视阅读法把整个代码过一遍,找到值得阅读的核心代码。

  2. 粗读这部分代码,将其内容进一步 breakdown。手边准备好笔和纸(或者其他趁手的工具),随时记录。记录最好的方式是图表。这个阶段的记录不建议用软件工具(除非有用着特别舒服的,能够人件合一的)。

  3. 精读这部分代码,结合你已有的知识,理解这个代码所需要的资料,猜测和还原代码中某种事件,消息,或者某个流程发生的场景。把猜测记录下来。这时,如果遇到外围的代码(调用了外部的函数),只要对理解不产生障碍,可以先放一下,把整个过程完整而详细地捋一遍再说。这个过程一定要多问问题,把「我以为我懂了但实际没懂」的情形尽可能减少。

  4. 用检视阅读法粗度剩下的代码,如果找到其他值得精读的代码,跳至 2。

  5. 使用对比阅读(或者说,主题阅读)方式,把类似功能的 repo 都扫一遍。尝试着用自己的语言消化不同作者的实现,关注其实现的差异,并试图评判这种差异。

  6. 用软件将手稿电子化,便于将来回顾。文字可以直接上笔记本工具(甚至可以尝试 gitbook),图表如果买不起 visio,omniGraffle 这样的工具,可以用 plantuml。使用方法参考我的文章:那些年,我追过的绘图工具

最后一步是个非常耗时的过程,除非你有惊人的毅力,或者好为人师,要把你的心得分享出去,否则,做的动力不大。当然,在这个场景下,我们是悠然自得地读代码,没有客户老板拿着鞭子在后面抽,所以读懂之后记忆会非常深刻,即便没有电子文档留存,回到代码翻一翻,记忆就能还原了。

再次反省:我第 6 步也做得不好,有些手稿,如果不拍成照片,就永远的丢失了。

(我对 app master 的初始化的简单总结)

这样的阅读做得越多,真正搞明白的理论,知识和算法越多,你就越是不可替代的大拿。有时候,其实我们只要认认真真花上几个月,搞明白某大型项目,基本就是人中龙凤了。

场景三:为了能级跃迁而阅读代码

中学物理告诉我们:原子在光的辐射下,吸收光子,可以从低能状态跳跃到高能状态,电子的轨道,或者说能级(energy level)会发生跃迁。这和哲学上常常提到的量变到质变异曲同工。作为一个程序员,你的发展历程也是这么一个过程:在工作中缓慢爬坡,到达一个平台便停滞不前,似乎股票走势上的箱体整理。然后突然有一段时间,不知道受了什么刺激(比如说野战打出了龙王神力,或者说读了程序人生*_*),突然连拉几个涨停上了另一个平台。

打破平台期,成就能级跃迁,你需要吸收合适的「光子」。这光子可以是一个开天辟地的项目(比如说 Google 的 Google Map,docker 的 docker,阿里的淘宝等),可是这样的机会并非总能被你我赶上,大多数人都是在日复一日地做些并不起眼的,只能缓缓升级的小活 —— 就像一个七级的英雄带着一群大雕,却只能天天怼大耳怪地狱恶犬狮鹫之流的野兵。这时候,与其默默沉沦,不若学庄子口中的北冥之鱼那样,沉潜浮动,积蓄能量,等待下一次抟扶摇而上九万里。

这种积蓄能量为跃迁准备的一种方式是读代码。读什么?读那些基础地不能再基础,你认为自己一辈子都不会去写的那些代码。比如 linux kernel,比如 OTP。这种读法,你不知何时能够完成,所以,要有足够的耐心和时间。检视阅读 + 主题阅读 + 思维导图是经常用到的方法。下图是 OTP 的源码我在检视阅读后,圈定的要逐渐阅读的部分,加粗的是我已经完成粗读的部分。

OTP 的代码不算少,但是耦合度非常低,其实最终是拆分成若干个场景二去阅读。我们看其代码总量:

1.4m loc,近乎恐怖。但除去 example 和一些无关的辅助代码后:

930k,小了约 45%。而我圈定的第一批阅读的代码,只有区区 130k 而已,不消两天可以粗读,顶多半年,可以精读。如此这般,半年后,你的水平必然非当日的吴下阿蒙了。

需要指出的是,这种阅读有时会让人非常沮丧,因为你会遇见非常非常之多的 knowledge gap,从而不得不翻书查资料弥补这些你缺失的知识点,拉慢了整个阅读理解的步伐 —— 有时甚至数日毫无进展,让你心中被激发出来的那口气开始渐渐衰竭。这时候,稳住!这些 knowledge gap 是上天馈赠的礼物,是你弥补 you don’t know what you don’t know 的绝佳机会。慢慢来,take it easy,享受获取额外知识的喜悦。

这样数年下来不断充实自己,你写代码做项目时,离余光中描绘的,令人神往的李白的「绣口一吐,就半个盛唐」的状态不远矣!

分享一个小故事,结束这篇文章:

在 Juniper 的早年,我在写 netscreen data plane 代码的总结(就是我在其他文章中提到过的被公司同事戏谑为『葵花宝典』的那份内部文档)时,因为想更加弄清楚 IPSec phase 1 SA 建立的过程,潜进了 IKE 的后花园。彼时我对 IKEv2 不甚了解,读了很多资料,然后才开始看代码。代码我看得懵懵懂懂,catcher,thrower 等奇奇怪怪的表述让我如同黄帝陷入了蚩尤的迷雾中不得方向。后来在同事的提醒下,我才知道那一堆术语都源自棒球,在 wikipedia 上搞懂了这些棒球术语的意思后,那些代码开始变得可爱起来。

几年以后,我第一次读了『如何阅读一本书』,作者用了一大段文字通过棒球的捕手的技巧来类比阅读的技巧,用捕手和投手的关系来类比读者和作者的关系,读者读者,我不禁回到了十多年前那个满是阳光的午后:我坐在宽敞的办公桌前,使用桌上的无盘 SunRay 工作站接入了一台以格林童话 Gretel and Hansel 命名的 solaris 服务器上,然后使用 vim 打开了 IKE 的建立连接,六次(不知道记忆是否还对)握手的代码,咂着香浓的咖啡,开始观看一场精彩纷呈的棒球比赛。。。