软件设计文档_软件设计文档何时休

最近在写软件设计文档，常常很疑惑：设计文档应该详细到何种程度呢？

参考了过往一些项目的设计文档，有的写的比较简略，有的写的比较详细。其中有一个设计文档是事后补的，写的很详细，连模块内部用的数据结构也详细地列了出来。我也很疑惑，难道真的要这样写设计文档吗？

女儿Susan问我小时候玩什么传统的游戏？我想了想说：抓石子。 抓石子是女孩喜欢玩的游戏，但我小时候也喜欢玩。女儿问：那应该如何描述呢？老师让写下来。

“呃，将石子撒在地上，从中捡起一个，抛向空中，与此同时，抓地上的石子，再…… 当然，石子大小要合适，直径大约在1.5~2cm，要圆一些，你喜欢方的也可以，也不能撒太开，否则……也不能抛太高和太低…...”

抓石子本身不难，但想要描述清楚，也不是一句话两句话说清楚的。我意识到，软件设计中有些东西本身不难，但要想把它描述好，既费力，也枯燥。这也是大家不愿写文档的原因之一。

听说一个其他的项目的设计文档也很详细，连窗口上菜单的也详细地列出来了，还为此讨论了多次，项目组成员苦不堪言。

最近读了一本关于软件架构的书：《恰如其分的软件架构》，其中提出了“风险驱动的设计方法”。

在架构设计方面，也存在这样的争论：做多少架构设计才是合适的？有的主张不做预先设计，开发者一上来就开始写代码，架构在构建时浮现。有的主张将10%的时间用于架构与设计，90%用于构建和测试。而有的主张开发者应采用一整套设计及文档技术，以产生完整的书面设计文档。

而风险驱动的设计方法遵循的指导原则是：为架构付出的努力应与失败的风险相称。为此要问：我的风险是什么？用于降低这些风险的最佳技术是什么？通过选择技术和架构设计，风险是否已经缓解？可以开始编码了吗？

我想，就我遇到的设计文档要详细到何种程度的问题，也可以采用这一方法。即，对于要开发的软件，哪些应详细论述，哪些可以一带而过。详细论述的部分，应是软件的难点，即如果这一点不说清楚，软件就没法实现，或实现起来心里没有底。

比如，对于多传感器数据融合软件，如果你不把数据融合方法说清楚，这个软件就难以开发出来。但如果之前已经开发了一版多传感器数据融合软件，现在要改进。那么，重点就不是数据融合方法，而是要改进的那部分。

又如，在现有软件中增加日志模块，虽然是新增的模块，但日志模块本身没有什么风险，因此也不算重难点，也没有必要详细描述。

又如，有一个模拟器软件，软件本身并没有多大的难度和风险，但此软件的开发者是个新手，所以开发者本身成为一个风险。这时，要做的可能就不是详细地设计软件，而是麻溜的赶紧写出一个Hello World来增强信心。

所以，根据软件系统的风险，适当地进行设计，做到Just Enough，才是合适的。