谷歌软件工程师是怎样写设计文档的？
极客时间编辑部
讲述：初明明大小：4.99M时长：05:28
你好，欢迎收听极客视点。
谷歌软件工程文化的主要元素之一就是通过设计文档定义软件设计。在开始项目编码工作之前，软件系统或应用程序的作者会创建这些相对非正式的文档。设计文档记录了高级实现策略和关键设计决策，并且重点记录了这些决策之间的权衡考虑。
设计文档的结构
设计文档是非正式文档，因此它们的内容不会遵循严格的准则。一个首要原则是，针对具体项目可以用任何最合理的形式编写。
话虽如此，形成的特定结构必定有其价值所在。
上下文和范围
这一部分会粗略地向读者介绍新系统是如何构建的以及实际情况如何。我们的目标是直接让读者了解最新情况，但先前的一些情况可以被推测或者能链接到详细信息。这个部分应该完全聚焦于客观背景事实。
目标和 non-goals
这一部分会列举出系统目标是什么，但有时候更重要的是，列出系统的 non-goals。non-goals 并不是像“系统不应该崩溃”这样的负面目标，而是那些本可以合理地成为目标但却明确地选择不作为目标的东西。
实际设计
这一部分应该从概述开始，然后扩展至详情。
设计文档适合写你在设计软件时所做的权衡。把重点放在这些权衡上，来产出具有长期价值的文档。换句话说，给定上下文（事实）、目标和 non-goals（需求），设计文档可以提供建议方案并展示为什么某个特定方案最能满足那些目标。
在比较正式的媒介上，编写文档的目的是提供灵活性，以适当的方式展示手头的问题。因此，对于如何真正地描述设计并没有明确的指南。
尽管如此，对于大部分设计文档来说，一些最佳实践和重复话题都很有意义：
系统语境图
在许多文档中，系统语境图都非常有用。它能将系统作为更大技术环境的一部分展示，允许读者结合他们已经熟悉的环境进行理解。
APIs
如果正在设计的系统暴露一个 API，那么勾勒出这个 API 通常是个好主意。然而，在大多数情况下，人们应该按捺住将正式接口或数据定义复制粘贴到文档中的诱惑，因为这些定义通常都很冗长，包含一些不必要的细节，而且很快就会过时。相反，人们应该聚焦于与设计及其权衡相关的部分。
数据存储
存储数据的系统应该讨论如何及用何种大致的形式存储数据，要聚焦于与设计及其权衡相关的部分。
代码与伪代码
除了一些描述新奇算法的场景，设计文档应该很少包含代码或伪代码。在适当的情况下，可以链接到设计实现的原型。
约束度
影响软件设计和设计文档形状的主要因素之一就是方案空间的约束度。
极端的一个例子就是“绿地软件项目”，我们都知道目标，而且解决方案可以是任何最有意义的方案。这样一个文档可能涉及面很广，但它还需要快速定义一组规则，来允许对一组可控的解决方案进行细致研究。
另一方面，系统中可能的方案都定义得很好，但是完全不清楚如何将它们组合起来实现目标。这可能是一个很难更改的遗留系统，而且它不是按照你希望的样子设计的，或者是一个程序库设计，需要在宿主编程语言的约束下运行。
在这种情况下，你也许能列举出相对容易做的事情，但你需要费些心思将这些事情组合起来，从而实现目标。可能有很多方案，但没有一个是非常好的，因此，这样一个文档应该聚焦于根据所有确定的权衡点来选择最佳方案。
可供考虑的备选方案
这部分会展示为什么被选中的方案是针对项目目标的最佳方案，以及读者可能想知道的，为什么其它方案提供的权衡针对目标方案是不太理想的。
交叉关注点
在这里，你的组织可以确保像安全性、隐私性、可观测性等跨领域问题被纳入考虑范围。这些通常都是相对短的部分，解释了设计如何影响这些关注点以及如何解决这些关注点。团队应该将这些关注点标准化。
由于它们的重要性，谷歌项目需要有一个专门的隐私设计文档，并且有专门的隐私和安全审查。虽然这些审查只需要在项目启动时完成，但最好尽早与隐私和安全团队接触，以确保设计从一开始就将这些考虑在内。
设计文档的长度
设计文档需要足够丰富凝练，以便忙碌的人可以真正阅读。一个比较大的项目最佳长度是 10-20 页。如果你的文档太长，最好将问题分解成多个可控的子问题，要保持简洁并且聚焦于一个有限的问题集。
以上就是今天的内容，希望对你有所帮助。
公开
同步至部落
取消
完成
0/2000
荧光笔
直线
曲线笔记
复制
AI
- 深入了解
- 翻译
- 解释
- 总结
该免费文章来自《极客视点》，如需阅读全部文章，
请先领取课程
请先领取课程
免费领取
© 版权归极客邦科技所有，未经许可不得传播售卖。 页面已增加防盗追踪，如有侵权极客邦将依法追究其法律责任。
登录 后留言
全部留言(1)
- 最新
- 精选
诺言设计文档在项目启动时确实很重要，但是随着迭代，就有点力不从心了。1
收起评论