导读：

很多开发者自己非常漠视技术文档的编写，然而又时常抱怨别人的技术文档不完善、质量差、更新不及时等等…… 这种在开发团队中普遍存在的矛盾甚至已经演变成了一个又一个段子。

下面请大家来看Google是如何写设计文档的。

谷歌软件工程文化的主要元素之一就是通过设计文档定义软件的设计。

在开始项目编码工作之前，软件系统或应用程序的作者会创建这些相对非正式的文档。设计文档记录了高级实现策略和关键设计决策，并且重点记录了这些决策之间的权衡考量。

作为软件开发工程师，其实我们的工作本质上不是生产代码，而是解决问题。

非结构化文本，类似设计文档的形式，也许是在项目早期解决问题比较好的工具，因为它易于理解、更简洁，且以比代码更高的层次来沟通问题与方案。

除软件设计的原始文档外，设计文档还实现了软件开发周期中的如下功能：

• 在早期发现设计问题，而那时变更的成本还比较小

• 在组织内围绕设计达成共识

• 确保考虑到交叉领域的问题

• 将高级工程师的知识扩展到组织中

• 围绕设计决策形成组织记忆的基础

• 在软件设计师的技术组合中充当总结工具

设计文档的结构

设计文档是非正式文档，因此在内容编写时不会遵循严格的规则。但是，一个重要的原则是，针对具体项目需要用任何最合理的形式编写。

而形成特定的文档结构也一定有它的价值所在。

上下文和范围

这一部分会粗略地向读者介绍新系统是如何构建的以及实际情况如何。

注意，这不是需求文档。请保持简洁！

我们的目标是直接让读者了解最新情况，但先前的一些情况可以被推测或者能链接到详细信息。这个部分应该完全聚焦于客观背景事实。

目标和 non-goals

这一部分会列举出系统目标是什么，但有时候更重要的是，列出系统的 non-goals。

注意，non-goals 并不是像“系统不应该崩溃”这样的负面目标，而是那些本可以合理地成为目标但却明确地选择不作为目标的东西。

一个很好的例子是“ACID 准则”；当设计数据库时，你肯定想知道这是一个目标还是一个非目标。而如果这是一个 non-goals，如果它不会阻碍目标的实现，那你仍然可以选择一个提供它的解决方案。

实际设计

这一部分应该从概述开始，然后逐步扩展至细节部分。

设计文档适合写你在设计软件时所做的各种权衡。把重点放在这些权衡上，然后来产出具有长期价值的文档。换句话说，给定上下文（事实）、目标和 non-goals（需求），设计文档可以提供建议方案，且展示为什么某个特定方案最能满足那些目标。

在比较正式的媒介上，编写文档的目的为提供灵活性，以适当的方式展示手头的问题。因此，对于如何真正地描述设计并没有明确的指南。

尽管如此，对于大部分设计文档来说，一些最佳实践和重复话题都很有借鉴意义：

系统语境图

在许多文档中， 系统语境图都非常有价值。这样一张图将系统作为更大技术环境的一部分展示，允许读者结合他们已经熟悉的环境进行理解。

系统上下文语境例子

APIs

如果正在设计的系统暴露一个 API，那么勾勒出这个 API 通常是个好主意。

然而在大多数情况下，人们应该按捺住将正式接口或数据定义复制粘贴到文档中的诱惑，因为通常这些定义都很冗长，包含一些不必要的细节，而且很快就会过时。相反，人们应该聚焦于与设计及其权衡相关的部分。

数据存储

存储数据的系统应该讨论如何及用何种大致的形式存储数据。和关于 API 的建议类似，并且理由相同，应该避免复制粘贴完整的模式定义。相反，要聚焦于与设计及其权衡相关的部分。

代码与伪代码

除了一些描述新奇算法的场景，设计文档应该很少包含代码或伪代码。在适当的情况下，可以链接到设计实现的原型。

约束度

影响软件设计和设计文档形状的主要因素之一就是方案空间的约束度。

极端的一个例子就是“绿地软件项目”，我们都知道目标，而且解决方案可以是任何最有意义的方案。这样一个文档可能涉及面很广，但它还需要快速定义一组规则，来允许对一组可控的解决方案进行细致研究。

另一方面，系统中可能的方案都定义得很好，但是完全不清楚如何将它们组合起来实现目标。这可能是一个很难更改的遗留系统，而且它不是按照你希望的样子设计的，或者是一个程序库设计，需要在宿主编程语言的约束下运行。

在这种情况下，你也许能列举出相对容易做的事情，但也需要费些心思将这些事情组合起来，从而实现目标。

有可能存在很多方案，但没有一个是非常好的，因此，这样一个文档应该聚焦于根据所有确定的权衡点来确定最佳方案。

可供考虑的备选方案

本节列出了能合理实现类似结果的备选设计。重点应该放在每个设计所做的权衡，以及这些权衡如何导致选择这个设计的决定，而这正是这个文档的首要主题。

虽然简略介绍最终没有被选中的方案也没有什么，但是本节会非常明确地展示为什么被选中的方案是针对项目目标的最佳方案，以及读者可能想知道的，为什么其它方案提供的权衡针对目标方案是不太理想的。

交叉关注点

在这里，你的组织可以确保像安全性、隐私性、可观测性等跨领域问题被纳入考虑范围。这些通常都是相对短的部分，解释了设计如何影响这些关注点以及如何解决这些关注点。团队应该将这些关注点标准化。

由于它们的重要性，谷歌项目有一个专门的隐私设计文档，并且有专门的隐私和安全审查。虽然这些审查只需要在项目启动时做完，但最好尽早与隐私与安全团队接触，以确保设计从一开始就将这些考量在内。

对于这些主题的专用文档，中心设计文档当然可以只引用它们，而不是详细介绍。

设计文档的长度

设计文档的文字需要足够丰富凝练，以便忙碌的人可以真正阅读。

一个较大的项目的文档最佳长度是 10-20 页。如果文档太长，最好将问题分解成多个可控的子问题。

值得一提的是，写一份 1-3 页的“迷你设计文档”也是绝对可行的。这对于敏捷项目中的增量改进或子任务特别有帮助——你仍然可以像处理一个长文档那样处理所有步骤，只需要保持简洁，且聚焦于一个有限的问题集。

什么时候不要写设计文档

写设计文档是有开销的。是否编写设计文档的决定归根结底于核心权衡，即围绕设计、文档、高级评审等方面达成共识的好处是否超过创建文档的额外工作负担。这个决策的核心在于设计问题的核心是否模棱两可——这取决于问题的复杂度或者方案的复杂度，或者兼而有之。如果设计问题的核心并不模糊，那么就几乎没有价值去编写一份文档。

如果设计文档实际上是实现手册，那么这就是一个设计文档不必要的明确指标。如果一个文档基本上在说“我们是如何实现的”，而不涉及权衡、替代方案和决策解释（或者这个方案是如此明显以至于不需要权衡），那么直接编写实际程序可能是个更好的主意。

最后，创建和审核一个设计文档的开销可能与创建原型和快速迭代不兼容。然而，大部分软件项目确实存在一些实际已知的问题。遵循敏捷开发方法并不是不花时间去解决实际已知问题的借口。

另外，原型构建本身可能就是创建设计文档的一部分。“我试过了，它起作用”是选择一个设计的最佳论据之一。

设计文档的生命周期

设计文档的生命周期的几个步骤是：

• 创建并快速迭代

• 审核（可能有多轮）

• 实现和迭代

• 维护和学习

创建和快速迭代

在这个阶段，我们也需要编写文档，有时会和一组队友合作编写。

当文档被分享给最了解问题领域的同事（通常属于同一个团队）时，这个阶段会快速演变到快速迭代期，通过他们将问题搞清楚以及提供建议，让文档进入第一个相对稳定的版本。

虽然你肯定会发现工程师甚至团队喜欢版本控制和代码评审工具来创建文档，但是谷歌的大部分设计文档是用 Google Docs 创建的，而且大量使用了它的协作功能。

评审

在评审阶段，设计文档会被分享到除初始作者和密切协作者之外的更广泛读者。评审可以带来许多价值，但它们也是危险的开销陷阱，所以需要明智地处理评审。

评审有多种形式：比较轻量的方式是将文档发送给（比较广泛的）团队列表中，让人们都有机会看一看。讨论主要发生在文档的评论环节。比较重的评审，是正式的设计评审会议，在会议上，作者将文档（通常是一个专门的演示文稿）展示给级别较高的工程师。谷歌的许多团队都会为此定期召开会议，工程师可以报名参与评审。当然，等待这些会议的召开会明显减慢开发进度。工程师可以通过直接寻求关键性反馈来缓解这种情况，而不是阻碍更广泛的评审流程。

当谷歌还是一个比较小的公司时，人们习惯于将设计发送到一个核心邮件列表，高级工程师在他们闲暇时评审这些设计。这可能是一个很好的方式来处理你公司的事情。其中一个好处是，这确实在公司中建立了一种相对非正式的软件设计文化。但是，当公司规模扩大到一个相对大的工程团队时，维持集中化的方式变得不再可行。

评审带来的主要价值是，它们提供了一个机会将组织的综合经验融入到设计中。最为一贯的是，评审阶段可以确保将跨领域的关注点，例如观测性、安全性和隐私性考虑在内。评审的主要价值不在于发现问题本身，而是在开发周期的早期就发现问题，此时进行更改的成本仍然相对较小。

实现和迭代

当事情进展到确信进一步评审不再需要对设计进行重大改动时，就可以开始实现了。当计划与现实冲突时，不可避免地会出现一些缺点、解决不了的需求、深思熟虑的猜测结果是错误的等情况，并且需要变更设计。这种情况下，强烈建议更新设计文档。

一般来说：如果设计的系统还没有交付，一定要更新文档。在实践中，我们人类都不擅长更新文档，而且由于其它实际原因，更改通常被独自放到新文档中。这导致最终状态有点类似美国宪法附带一堆修正案，而不是一份一致的文件。

从原始文档到这些修正文件的链接，对于将来尝试通过设计文档来理解目标系统的可怜的维护程序员是非常有用的。

维护和学习

当谷歌工程师面对一个他们从未接触过的系统时，他们的第一个问题通常是“设计文档在哪里？”。虽然设计文档和其它文档一样，会随着时间的推移与现实脱节，但它们仍然常常是人们了解系统创建思想的最容易入口。

作为作者，自我回顾并在 1 年或 2 年以后重新阅读你的设计文档。请问以下这些问题：

我们做对了什么？我们做错了什么？今天你怎么做才会做出不同的决定？回答这些问题是一个很好的方法，来实现工程师进阶和随着时间的推移提高软件设计技能。

结论

设计文档是一个很好的方法，用来在解决软件项目中最难问题的方面提高清晰度，并且达成共识。

设计文档节省了资金，因为它们可以通过预先调查，避免编写无法实现项目目的的“兔子洞”（ Rabbit holes ，源自《爱丽斯漫游仙境》，指通向未知世界的入口）；设计文档也损耗资金，因为创建和评审设计文档需要时间。

所以，针对你的项目，请明智地选择！

当考虑编写一个设计文档时，请考虑以下几点：

• 你是否不确定正确的软件设计，是否有必要花费前期时间来增加确定性？

• 与此相关的是，因为高级工程师可能无法审核每一次代码变更，因此请他们参与设计是否有帮助？

• 软件设计是否有模棱两可甚至是有争议的，而围绕设计文档在组织上达成共识是有价值的？

• 我的团队是否有时会忘记考虑设计中的隐私性、安全性、日志记录或其它的交叉问题？

• 是否强烈需要文档来对组织中的遗留系统的设计，以提供高层次的见解？

如果你对这些问题中的 3 个及以上的回答均为“是”，那么设计文档可能是开始你的下一个软件项目的好方法。

作者：Malte，Vercel首席技术官。此前，Malte是负责谷歌搜索渲染的首席工程师，以及Search on Laptops, Tablets, 和Desktop的工程总监。