1.什么是设计文件？
设计文档是软件工程设计的重要组成部分，是对技术问题解决方案的系统描述。 设计文档的目的是阐明设计的总体思路以及设计中考虑的权衡。
作为一名软件工程师，我们工作的本质不仅仅是编写程序代码，而是解决实际问题。 因此，与最终的程序代码相比，文本形式的设计文档可以在前期更简洁地传达信息，让读者了解问题并找到解决方案。
设计文档除了作为系统设计的最初表现形式外，在软件工程的开发周期中还发挥着以下重要作用：
通过设计文档，我们可以：
2.什么时候需要设计文件？
自己写设计文档是需要写作成本的。 如果问题的解决方案非常明确，没有明显的权衡，并且设计文档基本上是实现描述，那么设计文档应该被省略，直接实现。 也就是说，如果写一份设计文档的时间主要花在“写”而不是“思考”上，那么这个设计文档就可以省略。 当您考虑编写设计文档时，请考虑以下事项：
如果上述问题的答案是“是”，那么设计文档可能是开始下一个软件项目的好方法。
3、设计文档如何写？
在考虑使用设计文档来解决问题并开始准备设计文档之前，需要明确设计文档中容易混淆的三个概念。 它们也是创建设计文档的基础。 一旦出现偏差，我们精心编写的文档很可能完全无法使用，并且在纠正偏差时会返工大量工作，造成资源浪费。 因此，在编写设计文档之前需要了解这些先决条件。
3.1 编写设计文件的三个前提
明确了设计文档写作的三个前提条件后，就进入文档写作阶段。 设计文档是非正式文档，因此其内容不遵循严格的准则。 一个总的原则是针对项目的具体情况，可以用相对合理的方式来编写。 尽管如此，作者也根据文献和自己的经验提出了一些建议。
写作风格三要素
设计文档的写作也是技术写作（Technicalwriting），所以也强调以下三个要素：
设计文档的五个要点
设计系统和编写设计文档时需要注意的5个要点。
1.任何架构问题都是一种权衡。
在软件设计中，没有任何维度有绝对的优点或缺点。 每个设计决策都需要考虑许多竞争因素。 例如，可扩展性和效率是相互矛盾的； 长期效率与短期收益是相悖的； 规模提高了效率，但降低了灵活性。 “高内聚、低耦合”有利于迭代，但会增加短期开发成本。 NoSQL 的性能比 SQL 更高，但代价是功能大幅减少。 如果设计决策似乎没有权衡，通常是因为权衡尚未确定。 设计的时候应该从权衡的角度出发，在不同的需求之间找到平衡点。
2.“为什么”比“如何”更重要。
设计解决的问题往往是复杂和模糊的，因此解决方案往往不是唯一的。 对于工程设计来说，方案的论证通常比方案本身更重要。
3.考虑时间维度
在进行设计选择时，不能忽视时间维度，只设计某一阶段的最终状态。 设计需要考虑以下几个方面：
4.避免过度设计
在设计之初，定义问题的范围。
明确定义的问题是良好设计的必要条件。 不要迷信设计模型、设计模式、XX驱动的设计。 这些是工具，而不是法律。 不要为了制造问题而解决问题。 不要通过复杂的设计来表达工作的难度和深度：一个困难的问题可能有一个简单的答案。 不要太担心设计会很快被淘汰。 保持可扩展性，但不要在不知道的情况下浪费精力进行扩展。
【文章福利】另外，小编还整理了一些C/C++后台开发教学视频、相关面试题、后台学习路线图免费分享。 需要的话可以添加：点击跳转加入~群组文件共享
小编强烈推荐C++后端开发的免费学习地址：C/C++ Linux服务器开发/后端架构师【灵升教育】-学习视频教程-腾讯课堂
5. 总结
最重要的是知道如何设计以及你在设计什么。 列宁-克鲁格效应告诉我们，这可能并不明显。
我认为测试驱动设计很棒。 我这样做的次数比以前多了很多。 但是你可以测试你想要的所有东西，如果你不知道如何解决问题，你就不会得到解决方案。 ——《工作中的程序员》，彼得·诺维格
3.2 设计文档核心原则 前提1：设计文档读写比最高
在实现代码、系统接口、设计文档时，读写比（内容被大家读到的时间：写内容的时间）逐渐上升。 通常，设计供阅读的文档比编写文档花费更多的时间。 因此，在编写设计文档时，更多地考虑读者的体验而不是作者的体验。 为提高设计的可读性而投入的时间是非常值得的。
前提2：设计文档不是文学作品
设计文档的目的是传达设计，而不是表达自己。关注如何清晰简洁地表达而不是文采
前提3：设计文档是为谁而写的
首先，了解你的读者是谁？ 在良好的文档共享文化中软件设计开发说明书，读者不应该只是你的 TL 和设计文档的实现者。 设计文档的实际受众通常要大得多。 在不确定的时期，一个经验法则是假设读者群是：公司内的软件工程师，他们具有一定的工程经验，但对系统的上下文只有初步的了解。 通常，设计文档的范围越大，假定的受众就越多。 这意味着普通受众对目标系统了解较少，这意味着设计文档通常需要：
其次，考虑读者喜欢怎样阅读？ 大多数读者不会逐字阅读您的设计文档。 每个人都很忙。 读者通常只浏览一般结构，然后阅读（或跳过）他们感兴趣的部分。 读者喜欢“故事”。 以故事结构呈现内容是最容易被接受的，即使我们不需要讲述一个关于杀怪和升级的传统故事。 尽管故事的内容各不相同，但大多数故事都遵循一些基本模式。 例如，约瑟夫·坎贝尔总结说，世界上大多数神话故事都符合“英雄之旅”的模式——“出发、启蒙、回归”三幕。
对于设计文档/技术论文写作，通常安全的选择是Writing Science 引入的OCAR 故事结构。
设计文档通常遵循特定的组织结构，我们可以通过将每个结构映射到 OCAR 的不同部分来讲述一个故事。
最后，辩证地看待设计文档的可读性。 设计文档可读性与代码可读性都称为可读性，它们有一些共同点：
设计文档
代码文档
解释一下背景
解释一下上下文
强调原因/权衡/其他选择
强调为什么
防范措施
防范措施
代码能清楚表达的内容不需要文档
代码能清楚表达的内容不需要文档
3.3 设计文件的最佳实践措辞
措辞应简洁、准确、直白。
造句
”_系统形式的问题是如下问题：如何在系统中安排各种对象类型，使得较高的对象类型总是可以由较低的对象类型构造出来，也就是说，前者可以还原为后者。为了为了解决这个问题，我们必须研究各种不同类型的对象的相互约简性。
为此，我们必须根据所涉对象领域的实际科学知识，找到每个待研究对象基本事实存在的充分必要条件的各种可能性。 我们可以通过要求实际科学给出基本事实的（确定且恒定的）表述来做到这一点。 “摘录自：[德国]鲁道夫·卡尔纳普。《世界的逻辑结构》。”
段落
段落应尽可能短。 一般来说，一个段落不应超过8个完整的句子。 每一段都有一个且只有一个明确的主题。 每个段落都应该以主题句开头，以帮助读者快速理解该段落的主要思想。 段落中的每句话都应与主题密切相关； 否则，应添加新段落，或删除。
注意段落的流畅性。 段落句子应该以读者已经熟悉的概念开始，并在句末放置新的内容。 这样，读者就能更连贯地理解。
使用列表
使用项目符号来指示无序列表，并使用数字序列号来阐明顺序。 如何正确使用列表本文将不详细讨论。 将在后续文章中介绍。 您还可以查看文章末尾的参考资料。
结构长度
不要使设计文档太长。 文档中包含太多内容可能会让读者失去兴趣。
对于大型项目，大约 10 页（约 5000 字）的长度比较合适。 当超过这个长度时，可以考虑将问题拆分为子问题单独编写设计文档，并将子设计文档链接在总体设计文档中。
要逐步改进小问题，请考虑使用单寻呼机。 通常这类文档的范围较小，要解决的问题比较简单，目标用户群仅限于已经对问题有充分了解的内部成员。 这时，可以省略背景等内容，只采用目标-解决方案两段论证的结构。
排版
使用一致的字体。 用户不会意识到不同的字体意味着不同的东西，只会感到困惑。 微软雅黑是一个安全的选择。
不要使用不同的颜色来区分内容。 不要在文本中使用超过三种颜色。 您可以使用标志性颜色作为标题和标题，同时使用黑色作为正文。
附录：设计文档模板
设计文件没有公式。 尽管如此，作者还是参考了Google设计文档的结构和格式，并根据实际工作经验进行了改进。 这里有一个设计文档模板，供新手参考。 您可以使用此文档模板作为思考的基础。 通常不需要对每个部分进行详细填写，不相关的内容可以跳过。
目标
“我们要解决什么问题？”
用几句话描述设计文档的主要目的，以便读者一眼就能看出自己是否对设计文档感兴趣。 例如：“本文介绍了Spanner的顶层设计”
然后，使用要点来描述设计试图实现的重要目标，例如：
非目标也很重要。 非目标并不是纯粹目标的否定形式，也不是其他与解决问题无关的目标，而是一些读者可能意想不到的、本来可以是目标但并不存在的目标，比如：
设计并不是力求达到完美，而是力求达到平衡。 明确说明什么是目标、什么是非目标有助于读者理解后续设计决策的基本原理，也有助于检查在未来迭代设计时原始假设是否仍然成立。
背景
“我们为什么要解决这个问题？”
为设计文档的目标受众提供理解详细设计所需的背景信息。 根据读者群提供上下文。 目标读者的描述见上文。 设计文档应该是“自包含的”，即它们应该提供足够的背景知识，让读者无需进一步参考即可理解后续设计。 保持简洁，通常是几段，并对每段进行简要介绍。 如果需要向读者提供更多信息，最好只提供链接。 警惕知识诅咒（知识诅咒是一种认知偏差，人们在与他人交流时，下意识地认为对方拥有理解交流主题所需的背景知识）
背景通常可以包括：
不要在后台写下你的设计或问题的解决方案。
总体设计
“我们如何解决这个问题？”
在一页中描述高级设计。 描述系统的主要组件，以及一些关键的设计决策。 它应该描述系统的模块和决策如何满足前面列出的目标。
这个设计文档的审阅者应该能够根据整体设计来理解和评估你的设计思想。 对于不参与该项目的新腾讯工程师来说，该描述应该是可以理解的。
建议使用系统图来描述设计。 它可以让读者清楚地理解文中的新系统与已经熟悉的系统之间的关系。 它还可能包含新系统内部配置文件的构建块。
注意：不要只放图片而不做任何解释。 请根据上节的要求，用文字描述设计思路。
这里不描述细节，放在下一章； 这里不描述背景，放在前面的章节里。
详细设计
在本节中，除了介绍设计方案的细节之外软件设计开发说明书，还应该包括主要的设计思想以及生成最终方案过程中的权衡。 本节的结构和内容可以根据设计对象（系统、API、流程等）自由确定。 您可以将其分成几个小节，以更好地组织内容并尽可能以简洁明晰的结构阐明整个设计。
不要写太多的实现细节。 就像我们不建议添加仅说明“代码的用途”的注释一样，我们也不建议仅在设计文档中准确说明您希望如何实现系统。 不然为什么不直接实现呢？ 以下可能是不适合在设计文档中讨论的实现细节示例：
通常，这将包括以下内容（请注意，各部分的命名可以更改为更清楚地反映内容的标题）：
各子模块的设计
为了阐明一些复杂模块的内部细节，可以附上一些模块图和流程图来帮助读者理解。 可以借助时序图来演示，比如每个子模块中一次调用的运行过程。 每个子模块都需要解释其存在的意义。 如有必要，请勿添加模块。 除非有特殊情况（例如，设计文档是描述和实现核心算法），否则不要在系统设计中添加代码或伪代码。
API接口
如果您正在设计一个公开API接口的系统，简要描述API将有助于读者理解系统的边界。 避免将整个界面复制粘贴到文档中，因为特定编程语言中的界面通常很冗长，并且语言细节可能会快速更改。 只需关注 API 接口中与设计最相关的主要部分即可。
贮存
引入系统相关的存储设计。 如果答案不明显，本节应回答以下问题：
数据的抽象和数据之间关系的描述至关重要。 数据关系可以借助ER图（实体关系）来显示。
回答上述问题时，请尽可能提供数据，作为答案或辅助。 不要回答“数据规模很大，读写频繁”，而是回答“预计数据量为300T，每天读3M，每天写0.3M，峰值QPS为300”。 只有这样，才能为下一步具体的数据库建模提供详细的决策依据，才能让读者信服。 注：选择过程中还应考虑可能产生重大影响的非技术因素，例如成本。
避免将所有数据定义（数据模式）复制粘贴到文档中，因为数据模式更多的是实现细节。
其他选项
“为什么我们不以其他方式解决问题呢？”
在介绍最终方案之后，可以有一节介绍设计过程中考虑的其他设计方案（Alternatives based on），它们各自的优点、缺点和权衡，以及导致选择最终方案的原因解决方案。 通常，有经验的读者（尤其是方案审阅者）会很自然地想到一些其他的设计方案。 如果这里的介绍描述了这些方案没有被选中的原因，就会避免读者在看完整个设计后带着疑问来询问作者。 。 此部分能够体现设计的严谨性和全面性。
