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

1、设计文档是什么？

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

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

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

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

• 在可以低成本迭代的时候，尽早发现设计中的问题 - 设计左移，代价左移，快速失败（fail fast）

• 在团队中对设计达成一致 - 设计的本质是取舍(tradeoff)。几乎所有的架构设计决策都会被挑战，原因之一是：读者并非对所有的取舍都知晓，且与作者达成共识。在设计文档中清晰地列出取舍，有利于帮助读者了解（并认可）你的决策思路，减少被挑战的可能。

• 将资深工程师的经验和思想扩展到整个团队，帮助团队成长 - 作为作者，可以供资浅工程师学习 - 作为读者，可以审核资浅工程师的设计并提供建议

• 形成团队软件设计的一致方式，沉淀团队/公司技术积累 - 企业的生命力在于知识价值的积累

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

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

• 软件的规模是否较大，值得付出额外的编写评审设计文档的时间来降低失败的风险？

• 高级工程师无法确保 CR 每一份代码，让他们参与设计评审是否回报更高？

• 软件设计决策是模糊的，甚至有争议。有必要围绕设计文档在组织上达成共识?

• 是否需要通过设计文档强调项目交叉问题，如隐私性(Privacy)、安全性(Security)、日志记录？

• 是否有必要写一份文档来对有关遗留系统的设计问题提供高层次的分析？

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

3、设计文档要怎么写？

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

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

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

写作风格的三要素

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

• 清晰

• 简洁

• 优雅

设计文档的五个要点

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

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

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

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

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

3. 考虑时间维度

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

• 可维护性与可扩展性

• 考虑实现路径

• 考虑未来计划

4. 避免过度设计

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

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

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

小编强力推荐C++后台开发免费学习地址：