软件工程详细设计文档如何写一份高可读性的软件工程设计文档

导读1、设计文档是什么？设计文档是软件工程设计中的重要组成部分，是对一个技术问题的解决方案的系统性描述。设计文档的目的，是阐明设计的总体思想和设计中考虑的权衡点....1、设计文档是什么？

设计文档是软件工程设计中的重要组成部分，是对一个技术问题的解决方案的系统性描述。设计文档的目的，是阐明设计的总体思想和设计中考虑的权衡点。

作为一名软件工程师，我们的工作本质不仅仅是编写程序代码，而是解决真正的问题。因此，相比最终的程序代码，文字形式的设计文档，在早期能够更加简明扼要地传达信息，便于让读者理解问题，找到解决方案。

除了作为系统设计的最初体现，设计文档在软件工程的开发周期中起到下面重要作用：

通过设计文档，我们可以：

• 在可以低成本迭代的时候，尽早发现设计中的问题 - 设计左移，代价左移，快速失败（fail fast）
• 在团队中对设计达成一致 - 设计的本质是取舍(tradeoff)。几乎所有的架构设计决策都会被挑战，原因之一是：读者并非对所有的取舍都知晓，且与作者达成共识。在设计文档中清晰地列出取舍，有利于帮助读者了解（并认可）你的决策思路，减少被挑战的可能。
• 将资深工程师的经验和思想扩展到整个团队，帮助团队成长 - 作为作者，可以供资浅工程师学习 - 作为读者，可以审核资浅工程师的设计并提供建议
• 形成团队软件设计的一致方式，沉淀团队/公司技术积累 - 企业的生命力在于知识价值的积累

2、什么时候需要设计文档？

本身撰写设计文档是需要编写成本的。如果问题的解决方案非常清晰，没有明确的取舍，设计文档中基本都是实现描述，则应该省略设计文档而直接实现。换言之，如果编写设计文档的时间主要消耗在“写”而不是在“思考”上，则这个设计文档可省略。当你考虑编写一个设计文档时，想一想以下这几点：

• 软件的规模是否较大，值得付出额外的编写评审设计文档的时间来降低失败的风险？
• 高级工程师无法确保 CR 每一份代码，让他们参与设计评审是否回报更高？
• 软件设计决策是模糊的，甚至有争议。有必要围绕设计文档在组织上达成共识?
• 是否需要通过设计文档强调项目交叉问题，如隐私性(Privacy)、安全性(Security)、日志记录？
• 是否有必要写一份文档来对有关遗留系统的设计问题提供高层次的分析？

如果以上的问题的答案为“是”，那么设计文档可能是开始你的下一个软件项目的绝佳方法。

3、设计文档要怎么写？

在考虑通过用设计文档解决问题，开始着手准备设计文档前，需要厘清设计文档易混淆的三个概念，它们也是创作设计文档的根基。一旦出现偏差，我们认真撰写的文档很有可能完全不可用，在纠正偏差时也会出现大量工作返工，造成资源的浪费。所以，撰写设计文档前需要搞清楚这些前提。

3.1 撰写设计文档的三个前提

在搞清楚设计文档撰写的三个前提后，就会进入文档的编写阶段。设计文档是非正式的文档，因此他们的内容不会遵循严格的准则，一个首要原则是，针对项目的具体情况可以用相对合理的方式来编写。尽管如此，笔者也参考文献并结合自身经验给出一些建议。

写作风格的三要素

设计文档的写作也是技术写作（Technical Writing），因此同样强调以下三要素：

• 清晰
• 简洁
• 优雅

设计文档的五个要点

系统设计及编写设计文档时需要注意的 5 个要点。

1. 任何架构问题都是取舍。

在软件设计中，没有任何一个维度有绝对意义上的优劣。每一个设计决定都需要考量很多相违背的因素。例如，可扩展性和效率相背；长期效率和短期收益相背；规模化提升了效率，但降低了灵活性。“高内聚低耦合” 便于迭代，但是会增加短期的开发成本。NoSQL 比 SQL 性能高，但代价是功能的大幅降低。如果一个设计决策看上去没有任何的取舍，往往是因为取舍还没有被识别。在设计时应从取舍视角切入，寻找不同需求间的平衡。

2. “为什么” 比 “怎么做” 更重要。

设计所解决的问题往往是复杂而模糊的，因此，解决方案往往是不唯一的。对工程设计，方案的论证通常比方案本身更重要。

3. 考虑时间维度

做设计取舍时不能忽略时间维度，只设计某个阶段的终态。设计需要考虑以下方面：

• 可维护性与可扩展性
• 考虑实现路径
• 考虑未来计划

4. 避免过度设计

设计伊始，界定问题的范围。

一个良好界定的问题是一个良好设计的必要条件。不要迷信设计模型、设计模式、XX 驱动设计。这些是工具，而非法则。不要为了制造问题而解决问题。不要通过复杂的设计来体现工作的难度和深度: 一个困难的问题可能会有一个简单的答案。也不要过于担忧设计被迅速淘汰。保留可扩展性，但不要在未知时浪费精力扩展。

【文章福利】另外小编还整理了一些C/C 后台开发教学视频，相关面试题，后台学习路线图免费分享，需要的可以自行添加：点击 正在跳转 加入~群文件共享

小编强力推荐C 后台开发免费学习地址：C/C Linux服务器开发/后台架构师【零声教育】-学习视频教程-腾讯课堂

5. 总结

最重要的是要知道如何设计，知道自己在设计什么。列宁·克鲁格效应告诉我们，这未必显然。

I think test-driven design is GREat. I do that a lot more than I used to do. But you can test all you want and if you don’t know how to approach the problem, you’re not going to get a solution. ——Coders at Work, Peter Norvig

3.2 设计文档的核心原则前提一：设计文档的读写比最高

实现代码、系统接口、设计文档，读写比（内容被所有人阅读花费的时间：内容写作花费的时间）是逐步上升的。通常，设计文档供阅读读的时间往往远多于写的时间。因此，编写设计文档时就更多考虑读者的体验而非作者的体验。为提升设计可读性的时间非常值得投资。

前提二：设计文档不是文学写作

设计文档的目的是为了沟通设计，而不是为了自我表达。把精力放在如何清晰、简洁地表达，而非放在文采上

前提三：设计文档为谁而写

首先先了解你的读者是谁？在良好的文档分享文化下，读者不应该只是你的 TL 以及该设计文档的实施者，你的设计文档实际读者的范围往往大得多。在不确定的时候，经验做法是，假设的读者群体为：公司内部的、有一定工程经验的、但对该系统的上下文只有初步了解的软件工程师。通常，设计文档的范围越大，假定的受众群也会更大。这意味着受众对目标系统的平均了解程度更低，也就意味着设计文档往往需要：

• 更加详细的背景介绍
• 更少使用内部术语或缩写
• 更多阐述设计思路、取舍，更少解释具体实现细节

其次，考虑读者喜欢如何阅读？大部分读者不会逐字逐句阅读你的设计文档。大家都很忙。读者通常只会扫描大体结构，然后阅读（或者跳读）自己感兴趣的部分。读者喜欢“故事”。将内容以故事的结构呈现最容易被接受，即使我们并不是需要讲述一个传统的打怪升级的故事。虽然故事内容各有不同，但大部分故事都遵循一些基本的范式。例如，约瑟夫·坎伯 总结提出全世界大部分神话故事都符合“ 英雄之旅 ”-- “启程、启蒙、归程”三幕 -- 这个模式。

对于设计文档/科技论文写作，通用安全的选择是 Writing Science 所介绍的 OCAR 故事结构。

• Opening：开场，背景介绍
• Challenge：挑战，所要解决的问题
• Action：行动，执行的实验/设计/...
• Resolution：结果

设计文档通常遵循特定的组织结构，我们可以将每一个结构对应到 OCAR 的不同部分，以此讲述故事。

最后，辩证看待设计文档可读性。设计文档可读性 vs. 代码可读性都称作可读性，两者有些共通之处：

• 文档着重强调的内容应该是并非显而易见的事项：