编写设计文档的重要性

[AlexiaChen]

编写设计文档，有助于设计者能理清思路，理清系统背后的各种取舍，这样也可以帮助新人快速了解整个系统。在Google里面，软件工程师在开始一项功能，从小到大都需要编写一份设计文档的，而且设计文档还需要被其他工程师review。谷歌软件工程师是怎样写设计文档的？ - 知乎 (zhihu.com) (19 封私信 / 80 条消息) 在谷歌（Google）工作是怎样一番体验？ - 知乎 (zhihu.com)
我当时在harmony工作的时候，我发现我的直属Boss(他是从google出来的)，他也会有习惯先写一份设计文档，只是没有Google那么严格规范，比较随意。都是都有一份类似的蓝图设计，以及一些问题和取舍被描述。比如这一份设计文档 Design Change and Optimizations for 1-Second Finality · Issue #3722 · harmony-one/harmony (github.com)

我的前前Boos，也是一位区块链架构师，我第一次入门区块链，就是进去他自己从零开始写的FnFn区块链项目开始的，我也问过他相关的问题，怎样build system，他说了除了大量看别人的源码之外，就是在写代码前，先梳理下需求和功能，先想清楚怎样实现，其实大意也就是要写一份设计文档了，因为设计文档的内容也需要包含这些。

我看了几篇文章的理解就是，编写Design doc的首要目的，是要阐明背景的，系统的来龙去脉，更多的是展示What和Why，而不是How。在系统设计中，有些时候让人理解Why，What是比How重要得多的，这个话题其实已经被很多网络上的各种大神讨论过无数遍了。 所以设计文档展示的是一个high-level的设计，是一份蓝图。这里的设计文档是不需要多么详细的。

以下是两篇我觉得比较不错的文章，教你如何编写一份设计文档。

• https://people.eecs.berkeley.edu/~kubitron/courses/cs162-F06/design.html
• https://rinaarts.com/how-to-write-an-effective-design-document/