为可理解性而设计
摘要
来自 Google 内部 Code Health Summit 的一场演讲,主张随着 LLM 生成越来越多的代码,人类软件工程师应专注于判断力,并通过契约式设计、类不变量和模块化等理念来设计易于理解的系统。
<p><a href="https://lobste.rs/s/qsrnot/design_for_understandability">评论</a></p>
查看缓存全文
缓存时间: 2026/11/19 15:02
# 面向可理解性的设计
来源:https://jschuster.org/blog/2026/11/19/design-for-understandability/
*这是我 2025 年 11 月在 Google 内部 Code Health Summit 上所做演讲的讲稿。我在此分享,希望能引发更多的学习与讨论。*
## 摘要
在一个 LLM 为我们生成大部分代码的世界里,理解这些代码比以往任何时候都更加重要。但面对像 Google 代码库这样庞大而复杂的系统,软件工程师很容易陷入一种"习得性无助"的模式:你所能做的只是微调代码,然后祈祷它能通过测试。缺乏理解的 LLM,不过是一台全速运转的复杂性生成机器。
其实有更好的方法。正如我们这个行业已经学会了为可测试性(testability)而设计软件一样,我们同样可以为可理解性(understandability)而设计。我们可以运用契约式设计(design by contract)、类不变量(class invariants)、模块化(modularity)等理念,构建出可以逐块理解的系统,而不是继续往那团大泥球(big ball of mud)上堆积,然后祈祷它不要整个崩塌。
这容易吗?不容易。但值得吗?绝对值得。这些理念并非新概念,但它们远没有得到应有的广泛传授和深入理解;掌握它们,我们就能进入一个既对代码更有信心、又能同时提升开发速度的世界。
## 幻灯片与讲稿
大家好,感谢邀请!我们开始吧。
我想用一个问题开场:如果 LLM 能写代码,那人类软件工程师还剩下什么?
科技行业正迅速将希望寄托在大语言模型上,让它们替我们编写所有代码。但你可能会说:写代码不正是我们软件工程师的本职工作吗?那 SWE 的职责又在哪里?SWE 在 LLM 之上究竟贡献了什么不可替代的人类要素?
你们每个人对这个问题都会有不同的答案,这没关系。但下面是我的看法。
那个必要的人类要素就是**判断力**——判断代码是否可维护的判断力,判断代码是否健康的判断力。
LLM 可以遵循模式,生成与训练数据相似的代码。有时它们能针对某段代码给出有用的建议和批评。但做出"这段代码是否适合它所设计的任务"这一关键判断,仍然要靠你——人类。
因为事实是:今天的 LLM 仍然是个马虎的实习生。他们产出的代码有时很好,有时却完全跑偏,需要纠正。你不会在没有仔细审查的情况下就把一个马虎实习生的代码并入你的系统,所以你也不应该对 LLM 的代码这样做。
**你**要对代码的质量负责,无论这代码是 LLM 替你生成的,还是你老老实实用键盘一个字一个字敲出来的。
那么,这意味着什么呢?如果 LLM 将为我们编写大量代码,那么我们面对的未来是:人类花在写代码上的时间会越来越少,花在阅读和理解代码上的时间会越来越多——以确保它达到我们的质量标准。
这意味着,比以往任何时候都更重要的是:提升理解代码的能力,并加快阅读和理解的过程。
现在,如果你想在某件事上变得更好,为自己设定一个有挑战性的目标会很有帮助。这个目标应略高于你当前的水平,驱使你每天都变得更强。
我提议的目标是:**我们应该能够在不运行任何测试的情况下,预测每一行代码的行为。**
让我再说一遍:我们应该能够在不运行任何测试的情况下,预测每一行代码的行为。
我知道你可能在想:"理解每一行代码?不测试?你在开玩笑吗?!这里有太多复杂度和遗留代码了,我根本做不到!"
你可能确实这么想。如果我们撒手不管、放弃所有控制,你也许是对的。但我要告诉你,有更好的方法。
我们可以*设计*我们的代码,让它变得可理解。
回想一二十年前,我们曾认为为 API 中的每个公共方法编写多个测试是不可行的。不是因为不想做,也不是没尝试过,而是因为我们没有把代码设计到能在那个层面进行测试。但慢慢地,在整个软件行业中,我们改变了实践,转而为可测试性而设计。今天,为可测试性而设计已经深深融入我们的文化,做别的事反而几乎不可想象。我们同样可以为可理解性做这件事,让代码帮助我们更好地理解它。
我们自己的 Code Health 指南就为可理解性提出了有力的论据。它写道:"代码要可持续,就必须被理解。除非开发者知道系统目前提供什么、以及需要改变什么才能适应新情况,否则变更无法做出。因此,代码健康的关键要素包括良好的文档、易于理解的错误信息,以及清晰、简洁的代码。"
为可理解性而设计不仅重要,而且是一项可以学习的技能。它不是什么你天生有或没有的神奇能力。你可以采取具体、明确的行动来提升代码的可理解性。
今天我将向大家介绍其中几种。把它当作面向可理解性设计的"入门套件"。我们还会讨论贯穿所有这些实践的一条通用主题,这样到了某个阶段,你就能自己找到更多为代码设计可理解性的方法。
我今天要展示的理念并不新鲜。但它们即使被讲授,也远未达到应有的水平,而且我们大多数人对如何应用它们只有粗略的理解。我今天的目标,是把这种理解稍微打磨得更锋利一点,让它稍微更实用一点,从而启动一个让代码随时间变得更可理解的过程。
那么,让我们逐一介绍这些"面向可理解性设计"的实践。
## 契约式设计(Design by Contract)
为了引出这个理念,让我们先问一个问题:调用一个方法时,你应该依赖它什么样的行为?
假设我们有这样一个二分查找方法,但它的文档帮不上什么忙(你以前大概见过类似的东西)。
二分查找这个概念大家相当熟悉,但作为该方法的调用者,我们对这个具体实现有一些疑问。比如:
- 返回的索引是否总是第一次出现的位置?
- 如果找不到 `t` 会怎样?
- 如果列表未排序会怎样?
文档并没有回答这些问题。那我们能怎么办?
第一,我们可以猜测。但我们很可能会猜错。
第二,我们可以阅读代码。但这可能要花很长时间,尤其当我们关心的那个行为埋在好几层深处时。
第三,我们可以拿一些例子跑一跑测试,看看会发生什么。但仅仅因为在某些例子上是这样工作的,并不意味着对所有这类输入都是这样工作的。而且,即使现在是这样工作,也无法保证未来还会这样工作。
关键是:如果没有明确说明这段代码打算做什么,那么实现和意图之间就没有界限。想要使用这段代码的 SWE 就只能去猜:哪些行为是方法*承诺*保证的,哪些行为只是可能随时间变化的实现细节。
这就是契约(contract)的用武之地。
定义契约的方式有很多,但为了本次演讲,我将其定义为:对交互各方所承诺的可观察行为的一种较为正式的描述。
在现实世界中,一个基本的契约类似于"如果我做晚饭,你就洗碗"。
在编程中,一个例子可能是:"如果调用者提供一个非负整数 `n`,那么平方根函数返回 `n` 的平方根"。
让我们看看契约如何帮助我们处理二分查找的例子。
这是该函数的一个可能契约。它写道:"如果列表已排序,`binarySearch` 返回 `t` 在列表中第一次出现的索引,若未找到则返回 `-1`。对于未排序的列表,行为未定义。"
我们可以看到这个契约回答了我们提出的问题:
- 返回的索引是否总是第一次出现的位置?是的,契约明确说明了这一点。
- 如果找不到 `t` 会怎样?契约说 `binarySearch` 将返回 `-1` 来表示这种情况。
- 如果列表未排序会怎样?契约没有说明任何内容,因此这种行为是**有意**未定义的。这是一个合理的设计选择!出于性能原因,可能不想在运行时检查列表是否已排序。所以这个契约告诉用户:如果列表未排序,就不应依赖任何特定行为。相反,检查列表是否已排序的义务在于调用者,在调用 `binarySearch` 之前先做好检查。
契约的力量在于,它在作者的意图与实现之间划出了一条清晰的界限。调用者不再需要猜测行为:他们只需阅读契约,如果行为的某个具体细节没有出现在契约中,他们就知道这是未指定的。
在现实中,这并不总是完美的。无论有意还是无意,我们仍然会写出依赖实现细节而非指定行为的代码。但契约至少给了我们一种尽量减少这种行为的方式。
现在我们已经了解契约的样子,让我们谈谈契约如何帮助我们推理和理解代码。
假设你刚写了一个方法。我在这里把它画成一个小圆圈。
你想知道它是否正确。
我用紫色圆圈表示我们已经读过其代码的方法。
现在,你的方法并非孤立存在:它会调用其他代码。
于是你想:"好吧,我需要理解那些代码做什么。我要去读那些方法的代码。"
而那些方法又调用了其他方法,我们开始想这件事,琢磨该怎么推理那些方法。到这一步,你大概能猜到我要说什么了。
糟了。现在我们有成堆成堆的代码需要在整个代码库中阅读。
为什么仅仅为了推理一个方法,就需要这么多推理?这本来就是我们唯一想做的事啊!怎么会失控到这种地步?
那么,让我们退一步,这次用契约式设计重新来过。
你仍然要读自己的代码。这一点绕不过去;这正是我们刚刚做的改变。
而我们并没有改动代码。它仍然调用那些其他方法。
但现在,诀窍在于:我们只需阅读那些被调用方法的*契约*,而不是它们的代码。
就这样!我们可以停在这里了。我们不需要操心其他那些代码。契约已经告诉了我们调用这两个方法所需知道的一切。
其余的代码仍然存在,但我们可以不必去想它。契约抽象掉了所有那些对我们(作为这两个方法的调用者)无关紧要的行为。
这就是契约赋予我们的、用于推理代码的力量。
最后,我用几条编写契约的建议来结束这一节:
第一,记录你愿意承诺的行为。这通常就是你希望调用者依赖的行为。例如,你可能想记录方法的返回值。但错误信息里那些确切的人类可读文本?不必了。
第二,在契约中描述你的错误处理。契约不应、也不应该只关乎顺利路径(happy path)。如果你的方法可能以某种方式出错,请告诉调用者它可能在什么条件下出错,以及你将如何向调用者发出信号——无论是通过特殊的返回值、异常,还是其他方式。
最后,请记住:方法的调用者越多,契约就越难更改。如果它只是一个团队内部使用的私有方法?那改变契约并让调用者同步修改大概很容易。但如果它是一个被数百个其他项目使用的热门框架上的公共方法?那么重新协商契约就是代价高昂得多的工作,所以在决定这样做之前,你应该仔细权衡成本与收益。
以上就是我们面向可理解性设计"入门套件"中的第一个要素。
## 数据不变量(Data Invariants)
下一个要素是数据不变量。
让我用一个小故事来解释这个理念。
新冠疫情初期,我和妻子开始在家办公,我们怀念公司里的免费汽水。于是我们养成了在冰箱里存放健怡可乐(Diet Coke)罐装饮料的习惯。
但有个问题:我们很擅长从冰箱里拿饮料,却不怎么擅长补充新的进去。所以当你正在努力工作,盼着来一罐冰爽饮料休息一下时,打开冰箱却发现里面没有可乐,只能转而从储藏室里拿常温汽水喝,那真是相当扫兴。
问题在于,我们没有制定任何关于如何取用健怡可乐、如何补充冰箱的规则。没有任何规则约束对冰箱的访问,我们最终陷入了一个不想要的状态:在这个例子里,就是空冰箱。
代码中也会发生这种事。例如,假设你有这样一个 proto 来表示客户的订单 [注:"proto" 是 Google 的行话,指 Protocol Buffers 消息,类似于 JSON 对象]。如果你收到这个 proto,你有多相信 `total` 字段真的表示订单的总金额?
大概不太相信,对吧?这个 proto 可能来自代码的任何地方,所以不难想象有人忘了正确设置那个字段。
Proto 让你对数据底层表示拥有完全不受控的访问权限。Proto 非常适合在网络上来回传输数据,但如果你想排除某些状态,它们就不那么适用了。
为了解决这类问题,我们可以使用数据不变量。数据不变量是关于某段数据的一个永远为真的陈述。
数据不变量是一种有原则的方式,用来在数据中强制保证这些有效状态。如果运用得当,你可以避免代码中的大量 bug。
让我们看看如何用不变量来解决健怡可乐问题,以及你可能在自己的代码中遇到的类似问题。
第一步,确定你想要维护的不变量。
问问自己:你希望依赖这段数据的什么性质?代码中哪些地方会显式校验并在无效时返回错误?或者,你在哪些地方假定它是无效的,但实际上并不确定?
在这个例子中,我们想要的不变量是"冰箱里始终有一罐健怡可乐"。
第二步,你需要记录这个不变量。
需要注意的是,这是一个独立的步骤。在自己脑子里有一个不变量是一回事;把它写下来,让所有可能接触这段代码的人都知道,是另一回事。更不用说,如果你几个月或几年后再回到这段代码,你自己可能已经忘了当初想维护的到底是哪个不变量。
把它写在人们会看到的地方:可能是在相关的数据成员附近,也可能是在顶部的类级注释里。
第三步,在创建时建立不变量。通常这会在构造函数或工厂方法中完成。在这个例子中,我们构造冰箱时已经放入了几罐饮料。
[](https://jschuster.org/blog/wp-content/uploads/2026/10/page_46.png)第四步,每次修改数据时,确保你维护了这个不变量。
相似文章
迈向可理解的软件
本文批判了当前的编程实践和对大语言模型的依赖,反而主张通过更好的抽象、文档和软件栈来使代码更易于理解和维护。
像人类会维护它一样编写代码
文章警告说,依赖LLM编写代码而不保持良好模式,会教会AI不良习惯,导致代码库充满重复逻辑,代码质量不断恶化。
@dzhng: https://x.com/dzhng/status/2090252351533973768
这篇文章讨论了因人工审查瓶颈而产生的AI生成代码‘垃圾’问题,并指出软件工程必须演进,以系统设计为重点,而不是代码的可读性。
- -危险地跳过阅读代码 – olano.dev
文章认为,随着组织采用大语言模型进行代码生成,工程实践必须从审查生成的代码转向关注规格说明和测试,同时需要组织层面支持新流程。
google-labs-code/design.md
DESIGN.md 是来自 Google Labs 的格式规范,它将 YAML 设计令牌与 Markdown 文本相结合,为编码代理提供对设计系统的结构化理解,包括 lint 工具和 diff 比较。