软件需求设计文档怎么写 优秀的设计文档写法指南

谷歌软件工程文化的主要元素之一是通过设计文档定义软件设计。在开始项目编码工作之前，软件系统或应用程序的作者会创建这些相对非正式的文档。设计文档记录了高级实施策略和

谷歌软件工程文化的主要元素之一是通过设计文档定义软件设计。在开始项目编码工作之前，软件系统或应用程序的作者会创建这些相对非正式的文档。设计文档记录了高级实施策略和关键设计决策，并关注这些决策之间的权衡。

作为软件工程师，我们的工作本质上不是生产代码，而是解决问题。非结构化文本，类似于设计文档，可能是解决项目前期问题的更好的工具，因为它更容易理解，更简洁，在比代码更高的层面上沟通问题和解决方案。

除了软件设计的原始文档，设计文档还在软件开发周期中实现以下功能:

在早期发现设计问题，而那时变更的成本还比较小在组织内围绕设计达成共识确保考虑到交叉领域的问题将高级工程师的知识扩展到组织中围绕设计决策形成组织记忆的基础在软件设计师的技术组合中充当总结工具

文档是非正式文档，因此其内容不会遵循严格的准则。第一个原则是，它可以针对特定项目以任何合理的形式编写。

说了这么多，形成的具体结构肯定有它的价值。

本节将向读者粗略介绍新系统是如何构建的，实际情况是怎样的。这不是一个需求文档。请保持简单！我们的目标是让读者直接了解最新的情况，但之前的一些情况可以推测或链接到详细信息。这一部分应该完全着眼于客观背景事实。

这一部分将列出系统目标，但有时列出系统的非目标更重要。注意，非目标不是“系统不应该崩溃”之类的消极目标，而是本来可以合理定位但明确选择不定位的事情。一个很好的例子是“酸性标准”；在设计数据库的时候，你肯定想知道它是目标还是非目标。如果它是非目标，如果它不会阻碍目标的实现，那么你仍然可以选择提供它的解决方案。

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

设计文档适合写你在设计软件时所做的取舍。关注这些权衡，以产生具有长期价值的文档。换句话说，给定背景(事实)、目标和非目标(需求)，设计文档可以提供建议的方案，并显示为什么特定的方案能够最好地满足这些目标。

在更正式的媒体中，写文档的目的是提供灵活性，并以适当的方式显示手头的问题。因此，对于如何真正描述设计，并没有明确的指南。

然而，对于大多数设计文档来说，一些最佳实践和重复的主题是有意义的:

在许多文档中，系统上下文图非常有用。这样的图表将系统显示为更大的技术环境的一部分，允许读者结合他们已经熟悉的环境来理解它。

系统上下文图示例

如果正在设计的系统公开了一个API，概述这个API通常是一个好主意。然而，在大多数情况下，人们应该抵制将正式的接口或数据定义复制并粘贴到文档中的诱惑，因为这些定义通常很冗长，包含一些不必要的细节，并且很快就会过时。相反，人们应该关注与设计相关的部分及其权衡。

数据存储系统应该讨论如何以及以什么样的一般形式存储数据。类似于关于API的建议，出于同样的原因，应该避免复制和粘贴完整的模式定义。相反，把重点放在与设计及其权衡相关的部分。

除了一些描述新颖算法的场景，设计文档应该很少包含代码或伪代码。如果合适，您可以链接到设计实现的原型。

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

一个极端的例子是绿地软件项目。我们都知道目标，解决方案可以是任何最有意义的方案。这样的文档可能会覆盖广泛的领域，但它也需要快速定义一组规则，以允许对一组可控的解决方案进行详细的研究。

另一方面，系统中所有可能的方案都有很好的定义，但如何组合才能达到目标却完全不清楚。这可能是一个很难改变的遗留系统，也可能不是如你所愿的设计，或者是一个需要在宿主编程语言的约束下运行的库设计。

在这种情况下，你也许可以列出一些相对容易做到的事情，但你需要付出一些努力将这些事情结合起来才能实现你的目标。可能有很多方案，但都不是很好。因此，这样的文档应该集中于根据所有确定的权衡来选择最佳方案。

本节列出了可以合理实现类似结果的替代设计。重点应该放在每种设计所做的权衡，以及这些权衡如何导致选择这种设计的决定，这是本文的主题。

虽然简单介绍一下最终没有被选中的方案没什么，但这一节会清楚地说明为什么选中的方案是项目目标的最佳方案，读者可能想知道为什么其他方案提供的权衡对于目标方案来说并不理想。

在这里，您的组织可以确保安全性、隐私和可观察性等跨领域问题得到考虑。这些通常是相对较短的章节，解释设计如何影响这些问题以及如何解决它们。团队应该将这些问题标准化。

由于它们的重要性，Google Project需要有一个特殊的隐私设计文档和一个特殊的隐私和安全审查。虽然这些审查只需要在项目开始时完成，但最好尽早与隐私和安全小组取得联系，以确保设计从一开始就考虑到这些因素。对于这些题目的专项文档，中央设计文档当然只能引用而不能详细介绍。

设计应该足够丰富和简洁，以便忙碌的人可以真正阅读它。大型项目的最佳长度是10-20页。如果你的文档太长，最好把问题分解成几个可控的子问题。值得一提的是，写一份1-3页的“迷你设计文档”是绝对可行的。这对于敏捷项目中的增量改进或子任务特别有帮助——您仍然可以像处理一个长文档一样处理所有步骤，只需保持它的简洁并专注于有限的问题集。

写设计文档是有费用的。是否写设计文档的决定归结为核心的权衡，即围绕设计、文档、高级评审等达成共识的好处。超过创建文档的额外工作量。这个决定的核心在于设计问题的核心是不是模棱两可——这取决于问题的复杂程度或者方案的复杂程度，或者两者都有。如果设计问题的核心不模糊，写文档就没什么价值。

如果设计文档实际上是一个实施手册，那么这是设计文档的一个不必要的清晰指标。如果一个文档基本上说的是“我们是如何实现的”，但不涉及权衡、替代方案和决策解释(或者这个方案太明显了，不需要权衡)，那么直接写实际的程序可能是一个更好的主意。

最后，创建和评审设计文档的开销可能与原型和快速迭代不兼容。然而，大多数软件项目确实有一些已知的问题。遵循敏捷开发方法不是不花时间解决实际已知问题的借口。此外，原型本身可能是创建设计文档的一部分。“我试过了，效果不错”是选择设计的最佳理由之一。

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

创建并快速迭代审核（可能有多轮）实现和迭代维护和学习

在这个阶段，您编写文档。有时它是与一群作者合作写的。

当文档与最了解问题区域的同事(通常属于同一个团队)共享时，这个阶段会迅速演化为快速迭代期，通过他们，文档会进入第一个相对稳定的版本。

虽然你肯定会发现工程师甚至团队喜欢用版本控制和代码审查工具来创建文档，但是Google的大部分设计文档都是用Google Docs创建的，而且它的协作特性被广泛使用。

在审阅阶段，除了原始作者和密切合作者之外，设计文档还将与更广泛的受众共享。评论可以带来很多价值，但也是危险的开销陷阱，所以要明智地处理评论。

审阅的形式有很多种:比较轻松的方式是将文档发送到(更广泛的)团队列表中，以便人们有机会看一看。讨论主要发生在文档的评论部分。更重要的评审是正式的设计评审会议，在会上作者将文档(通常是一个特殊的演示文稿)提交给更高级别的工程师。谷歌的许多团队为此定期召开会议，工程师可以报名参加评审。当然，等待这些会议显然会拖慢开发进度。工程师可以通过直接寻求关键反馈来缓解这种情况，而不是阻碍更广泛的审查过程。

当谷歌是一家相对较小的公司时，人们习惯于将设计发送到一个核心邮件列表，高级工程师在业余时间审查这些设计。这可能是处理你公司事务的好方法。好处之一是它确实在公司建立了一种相对非正式的软件设计文化。然而，当公司的规模扩大到一个相对较大的工程团队时，保持集中化的方法不再可行。

评审的主要价值在于它们提供了一个将组织的全面经验整合到设计中的机会。最一致的是，审查阶段可以确保跨学科的关注点，如可观察性、安全性和隐私性，都被考虑在内。评审的主要价值不是发现问题本身，而是在开发周期的早期发现问题，那时进行更改的成本还比较小。

当事情进展到我们确信进一步的审查不需要对设计进行重大修改的时候，我们就可以开始认识到这一点了。当计划与现实发生冲突时，必然会产生一些缺点，无法解决的需求，深思熟虑的猜测结果是错误的，需要改变设计。在这种情况下，强烈建议更新设计文档。

一般来说，如果设计的系统还没有交付，文档必须更新。实际上，我们人类并不擅长更新文档，由于其他实际原因，更改通常会单独放入新文档中。这导致了一个有点类似于美国宪法的最终状态，有一堆修正案，而不是一个一致的文件。从原始文档到这些修改过的文档的链接，对于那些以后会试图通过设计文档来理解目标系统的糟糕的维护程序员来说是非常有用的。

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

作为一个作者，在1或2年后自我检讨和重新阅读你的设计文件。你做对了什么？你做错了什么？今天你能做什么来做出不同的决定？随着时间的推移，回答这些问题是提升工程师和改进软件设计技能的好方法。

在解决软件项目中最困难的问题时，文档设计是提高清晰度和达成共识的好方法。文档的设计很省钱，因为可以避免通过事先调查写出无法达到项目目的的“兔子洞”(译者注，兔子洞源自《爱丽丝梦游仙境》，指的是未知世界的入口)；设计也要花钱，因为创建和审查设计文档需要时间。所以，明智地选择你的项目吧！

在考虑撰写设计文档时，请考虑以下几点:

你是否不确定正确的软件设计，是否有必要花费前期时间来增加确定性？与此相关的是，因为高级工程师可能无法审核每一次代码变更，因此让他们参与设计是否有帮助？软件设计是否模棱两可甚至是有争议的，而围绕设计文档在组织上达成共识是有价值的？我的团队是否有时会忘记考虑设计中的隐私性、安全性、日志记录或其它交叉问题？是否强烈需要文档来对组织中的遗留系统的设计提供高层次的见解？

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