什么时候不要写设计文档？
极客时间编辑部
讲述：丁婵大小：7.64M时长：05:34
你好，欢迎收听极客视点。
写设计文档是有开销的，什么时候要写文档以及什么时候不要写文档，怎么判断呢？此前，谷歌首席工程师马尔特·乌布（Malte Ubl）发文分享了谷歌软件工程师写设计文档的一些思考，其中提到了什么时候该写文档什么时候不该写。InfoQ 对其进行了翻译，供你参考。
是否编写设计文档的决定归根结底于核心权衡，即围绕设计、文档、高级评审等方面达成共识的好处是否超过创建文档的额外工作负担。这个决策的核心在于设计问题的核心是否模棱两可——这取决于问题的复杂度或者方案的复杂度，或者兼而有之。如果设计问题的核心并不模糊，那么就几乎没有价值去编写一份文档。
如果设计文档实际上是实现手册，那么这就是一个设计文档不必要的明确指标。如果一个文档基本上在说“我们是如何实现的”，而不涉及权衡、替代方案和决策解释（或者这个方案是如此明显以至于不需要权衡），那么直接编写实际程序可能是个更好的主意。
最后，创建和审核一个设计文档的开销可能与创建原型和快速迭代不兼容。然而，大部分软件项目确实存在一些实际已知的问题。遵循敏捷开发方法并不是不花时间去解决实际已知问题的借口。另外，原型构建本身可能就是创建设计文档的一部分。“我试过了，它起作用”是选择一个设计的最佳论据之一。
设计文档的生命周期的几个步骤是：
创建并快速迭代
审核（可能有多轮）
实现和迭代
维护和学习
创建和快速迭代
在这个阶段，你编写文档。有时会和一组作者合作编写。
当文档被分享给最了解问题领域的同事时，这个阶段会快速演变到快速迭代期，通过他们将问题搞清楚以及提供建议，让文档进入第一个相对稳定的版本。
评审
在评审阶段，设计文档会被分享到除初始作者和密切协作者之外的更广泛读者。
评审有多种形式：比较轻量的方式是将文档发送到（比较广泛的）团队列表中，让人们都有机会看一看。比较重的评审，是正式的设计评审会议，在会议上，作者将文档展示给级别较高的工程师。谷歌的许多团队都会为此定期召开会议，工程师可以报名参与评审。
评审带来的主要价值是，它们提供了一个机会将组织的综合经验融入到设计中。评审阶段可以确保将跨领域的关注点，例如观测性、安全性和隐私性考虑在内。评审的主要价值不在于发现问题本身，而是在开发周期的早期就发现问题，此时进行更改的成本仍然相对较小。
实现和迭代
当事情进展到确信进一步评审不再需要对设计进行重大改动时，就可以开始实现了。当计划与现实冲突时，不可避免地会出现一些缺点、解决不了的需求、错误的结果等情况，并且需要变更设计。这种情况下，强烈建议更新设计文档。
一般来说：如果设计的系统还没有交付，一定要更新文档。在实践中，人类都不擅长更新文档，而且由于其它实际原因，更改通常被独自放到新文档中。这导致最终状态有点类似美国宪法附带一堆修正案，而不是一份一致的文件。从原始文档到这些修正文件的链接，对于将来尝试通过设计文档来理解目标系统的可怜的维护程序员是非常有用的。
维护和学习
当谷歌工程师面对一个他们从未接触过的系统时，他们的第一个问题通常是“设计文档在哪里？”虽然设计文档和其它文档一样，会随着时间的推移与现实脱节，但它们仍然常常是了解系统创建思想的最容易的入口。
作为作者，自我回顾并在 1 年或 2 年以后重新阅读你的设计文档。你做对了什么？你做错了什么？今天你怎么做才会做出不同的决定？回答这些问题可以帮助你实现工程师进阶和提高软件设计技能。
另外，当你考虑编写一个设计文档时，想一想以下几点：
你是否不确定正确的软件设计，是否有必要花费前期时间来增加确定性？
与此相关的是，因为高级工程师可能无法审核每一次代码变更，因此让他们参与设计是否有帮助？
软件设计是否模棱两可甚至是有争议的，而围绕设计文档在组织上达成共识是有价值的？
团队是否有时会忘记考虑设计中的隐私性、安全性、日志记录或其它交叉问题？
是否强烈需要文档来对组织中的遗留系统的设计提供高层次的见解？
如果你对这些问题中的 3 个及以上回答为“是”，那么设计文档可能是开始你的下一个软件项目的好方法。
以上就是今天的内容，希望能给你带来参考价值。
公开
同步至部落
取消
完成
0/2000
荧光笔
直线
曲线笔记
复制
AI
- 深入了解
- 翻译
- 解释
- 总结
该免费文章来自《极客视点》，如需阅读全部文章，
请先领取课程
请先领取课程
免费领取
© 版权归极客邦科技所有，未经许可不得传播售卖。 页面已增加防盗追踪，如有侵权极客邦将依法追究其法律责任。
登录 后留言
精选留言
由作者筛选后的优质留言将会公开显示，欢迎踊跃留言。
收起评论