本文介绍了谷歌的设计文档文化，希望能帮助大家在软件项目中做出明智的选择。Google软件工程文化的主要元素之一是通过设计文档定义软件设计。软件系统或应用程序的作者在开始对项目进行编码工作之前创建这些相对非正式的文档。设计文档记录了高级实施策略和关键设计决策，并强调了这些决策之间的权衡。作为软件工程师，我们的工作本身不是生成代码，而是解决问题。以设计文档形式出现的非结构化文本可能是在项目早期解决问题的更好工具，因为它比代码更容易理解、更简洁，并且可以在更高的层次上交流问题和解决方案。除了软件设计的原始文档之外，设计文档在软件开发周期中还具有以下功能：在变更成本相对较小时及早发现设计问题在组织内围绕设计建立共识确保跨部门考虑切割问题将高级工程师的知识扩展到组织中围绕设计决策形成组织记忆的基础作为软件设计人员技术组合中的总结工具1.设计文档的结构设计文档是非正式文档，因此它们的内容不会遵循严格的指导方针。一个总体原则是它可以用对特定项目最有意义的任何形式来编写。话虽如此，所形成的特定结构必须具有价值。上下文和范围部分向读者简要概述了新系统的构建方式及其实际外观。这不是需求文档。请保持简单！我们的目标是让读者直接了解最新信息，但可以推测或链接到一些以前的故事。本节应完全关注客观背景事实。目标和非目标部分列出了系统目标是什么，但有时更重要的是，列出了系统的非目标。请注意，非目标不是像“系统不应该崩溃”这样的消极目标，而是可以合理地作为目标但明确选择不作为的事情。一个很好的例子是“ACID指南”；在设计数据库时，你肯定想知道这是否是一个目标。如果它不是目标，如果它不妨碍目标的实现，那么你仍然可以选择提供它的解决方案。实际的设计部分应该从概述开始，然后扩展到细节。设计文档非常适合写下您在设计软件时所做的权衡。关注这些权衡以产生长期价值的文档。换句话说，给定上下文（事实）、目标和非目标（要求），设计文档可以建议解决方案并说明为什么特定解决方案最能满足这些目标。在更正式的媒体中，编写文档的目的是提供灵活性，以适当的方式呈现手头的问题。因此，没有关于如何实际描述设计的明确指南。尽管如此，对于大多数设计文档，一些最佳实践和重复出现的主题是有意义的：系统上下文图系统上下文图在许多文档中都很有用。这样的图表将系统呈现为更大技术环境的一部分，允许读者在他们已经熟悉的上下文中理解它。https://en.wikipedia.org/wiki/System_context_diagram系统上下文图示例API如果您正在设计的系统公开了一个API，通常最好绘制该API的草图。然而，在大多数情况下，人们应该抵制将正式接口或数据定义复制并粘贴到文档中的诱惑，因为这些定义通常很长，包含不必要的细节，并且很快就会过时。相反，人们应该关注与设计相关的部分及其权衡。存储数据的数据存储系统应该讨论如何以及以什么一般形式存储数据。与关于API的建议类似，出于同样的原因，应该避免复制粘贴完整的模式定义。相反，应关注与设计及其权衡相关的部分。代码和伪代码除了一些描述新颖算法的场景外，设计文档应该很少包含代码或伪代码。在适当的情况下，原型可以链接到设计实现。约束度影响软件设计和设计文档形状的主要因素之一是解决方案空间的约束度。一个极端的例子是“绿地软件项目”，我们都知道目标和解决方案可以是最有意义的。这样的文档可能很广泛，但它也需要快速定义一组规则，以便仔细研究一组受控的解决方案。另一方面，系统中可能出现的场景都定义的很好，但是完全不清楚如何将它们组合起来以达到目标。它可能是一个难以更改且未按照您希望的方式设计的遗留系统，或者是一个需要在宿主编程语言的约束下工作的库设计。在这种情况下，您可能能够列出相对容易的事情来做，但您需要考虑将这些事情放在一起以实现您的目标。可能有很多解决方案，但没有一个是非常好的，因此这样的文档应该侧重于根据所有确定的权衡选择最佳解决方案。2.考虑的备选方案本节列出了可以合理实现类似结果的备选设计。重点应该放在每个设计所做的权衡以及这些权衡如何导致选择该设计的决定，这是本文档的首要主题。虽然可以简要描述最终未选择的选项，但本节非常清楚为什么选择的选项是项目目标的最佳选项，而且读者可能想知道，为什么其他选项提供交易-目标关闭情况不太理想。横切关注点在这里，您的组织可以确保考虑安全、隐私、可观察性等横切问题。这些通常是相对较短的部分，用于解释设计如何影响这些问题以及如何解决这些问题。团队应该标准化这些问题。由于其重要性，谷歌项目需要有专门的隐私设计文档，并有专门的隐私和安全审查。虽然这些审查只需要在项目启动时完成，但最好尽早与隐私和安全团队合作，以确保设计从一开始就考虑到这些。对于这些主题的专门文档，中央设计文档当然可以只引用它们而不是详细介绍。设计文档长度设计文档需要足够丰富和简洁，以便忙碌的人可以真正阅读它们。较大项目的合适长度是10-20页。如果您的文档太长，最好将问题分解为可管理的子问题。值得一提的是，写一个1-3页的“minidesigndoc”是绝对可行的。这对于敏捷项目中的增量改进或子任务特别有用——您仍然可以像处理一个长文档一样处理所有步骤，只需保持简洁并专注于一组有限的问题即可。3.什么时候不写设计文档写设计文档是有开销的。是否记录设计的决定归结为一个核心权衡，即围绕设计、文档、高层审查等达成共识的好处是否超过创建文档的额外努力。这个决定的核心是设计问题的核心是否模糊——取决于问题的复杂性或解决方案的复杂性，或两者兼而有之。如果设计问题的核心不晦涩难懂，写文档的价值不大。如果设计文档真的是实施手册，那么这就清楚地表明设计文档是不必要的。如果文档基本上只是说“我们是如何做到的”，而没有进行权衡、备选方案和决策解释（或者解决方案非常明显，不需要权衡），那么只编写实际程序可能是更好的主意。最后，创建和审查设计文档的开销可能与创建原型和快速迭代不兼容。然而，大多数软件项目确实存在一些实际已知的问题。遵循敏捷开发方法并不是不花时间解决真正已知问题的借口。或者，原型制作本身可能是创建设计文档的一部分。“我试过了，它起作用了”是选择设计的最佳论据之一。4.设计文档生命周期设计文档生命周期中的步骤是：创建和快速迭代审查（可能多轮）实施和迭代维护和学习创建和快速迭代在此阶段，您编写文档。有时是与一组作者合作编写的。当文档与最了解问题领域的同事（通常属于同一个团队）共享时，这个阶段会迅速演变为快速迭代期，通过这个阶段他们澄清问题并提供建议，使文档进入第一个相对稳定的阶段版本。虽然您肯定会发现工程师甚至团队更喜欢使用版本控制和代码审查工具来创建文档，但Google的大部分设计文档都是使用GoogleDocs创建的，并大量使用其协作功能。审阅在审阅阶段，设计文档与原作者和密切合作者以外的更广泛的受众共享。评论可以带来很多价值，但它们也是一个危险的开销陷阱，因此请明智地处理评论。审查有多种形式：更简单的方法是将文档发送到（更广泛的）团队列表，让人们有机会查看它。讨论主要发生在文档的评论部分。较重的审查是正式的设计审查会议，作者在会议上向高级工程师展示文件（通常是专门的演示文稿）。Google的很多团队为此定期召开会议，工程师可以报名参加评审。当然，等待这些会议召开可能会大大减慢开发速度。工程师可以通过直接寻求关键反馈来缓解这种情况，而不是阻止更广泛的审查过程。当谷歌是一家相对较小的公司时，人们习惯于将设计发送到核心邮件列表，高级工程师在闲暇时审查它们。这可能是开展业务的好方法。好处之一是这确实在公司中建立了一种相对非正式的软件设计文化。然而，当公司规模扩大到一个相对较大的工程团队时，保持集中的方法就不再可行了。审查带来的主要价值是它们提供了一个机会，可以将组织的综合经验纳入设计。最一致的是，审查阶段确保考虑到诸如可观察性、安全性和隐私等交叉问题。审查的主要价值不在于发现问题本身，而在于在开发周期的早期发现问题，此时进行更改的成本仍然相对较小。实施和迭代当事情进展到进一步审查不再需要对设计进行重大更改时，实施就可以开始了。当计划与现实发生冲突时，难免会出现一些不足、未解决的需求、经过深思熟虑的猜测结果是错误的等等，需要进行设计变更。在这种情况下，强烈建议更新设计文档。总的来说：如果设计的系统还没有交付，一定要更新文档。在实践中，我们人类不太擅长更新文档，并且由于其他实际原因，更改通常会自己放入新文档中。这导致最终状态有点类似于带有一系列修正案的美国宪法，而不是一个连贯的文件。从原始文档到这些编辑文件的链接对于将来试图通过设计文档了解目标系统的可怜的维护程序员非常有用。维护和学习当谷歌工程师面对一个他们从未接触过的系统时，他们的第一个问题通常是“设计文档在哪里？”。虽然设计文档与其他任何文档一样，随着时间的推移可能会与现实脱节，但它们通常仍然是了解系统创建背后思想的最简单切入点。作为作者，请回顾一下自己，并在1或2年后重新阅读您的设计文档。你做对了什么？你做错了什么？你今天会做什么来做出不同的决定？回答这些问题是作为工程师取得进步并随着时间的推移提高软件设计技能的好方法。5.结论设计文档是提高清晰度和就解决软件项目中最困难的问题达成共识的好方法。设计文档可以节省资金，因为可以预先研究它们并避免编写不符合项目目的的“兔子洞”；设计文档也会浪费资金，因为创建和审查设计文档需要时间。因此，请为您的项目明智地选择！在考虑编写设计文档时，请考虑以下因素：您是否不确定软件设计是否正确，是否有必要预先花费时间来增加确定性？相关地，由于高级工程师可能无法审查每个代码更改，让他们参与设计是否有帮助？软件设计是否模棱两可甚至有争议，而围绕设计文档达成组织共识是有价值的？我的团队有时会忘记考虑设计中的隐私、安全、日志记录或其他交叉问题吗？是否强烈需要文档来提供对组织中遗留系统设计的高级见解？如果您对其中3个或更多问题的回答是肯定的，那么设计文档可能是开始您下一个软件项目的好方法。
