关于软件设计文档

1，为什么要设计文档模板

可以说现在是软件过程的年代，从重量级的CMM(I)、RUP到轻量级的XP…。重量级的过程(CMM(I)、RUP等)强调文档在软件开发过程中的核心地位，而轻量级的过程(XP等)则强调以Code为主、文档为次。可以看出它们都强调了文档的重要性。

1  为什么要有设计文档？

l 好的设计文档可以帮助开发者 “整理清楚个人的思路”

l 好的设计文档可以帮助团队“有效的交流沟通”

2  为什么要有模板？

l 好的模板不是固化而是引导开发者的思路

l 好的模板可以提供文档的一致性、可读性

 

因此，我们需要一份设计文档模板来引导而非固化我们对问题的认识和思考，规范文档的书写、提高文档的可读性和一致性以及可重用性，进而来帮助我们进行有效的沟通。

 

2.     设计文档模板内涵

如果一个东西只流于形式，而没有真正的内涵，那么它的作用将微乎其微，而且日久就会被遗弃，设计文档模板也不例外。因此设计文档模板是应该有内涵的，应该体现人性，而不是去刻意以某种规则去固化人对问题的认识和思考。

下表列出了我对于设计文档模板内涵的一些理解：

编号

内涵

基本描述

1

历史性

设计文档模板应该体现出文档的历史，不但可以利于日后的维护，还可以依文寻人、避免重蹈覆辙等。

2

文学性

设计文档模板应该有一定的良好的组织方式来引导人的思路以及思考方式(既象小说又象新闻)

3

艺术性

文设计档模板应该有好的展现形式，来提高衍生出来的文档的美感

4

科学性

设计文档模板应该体现出软件设计的基本的方法论以及基本思想(如面向对象+敏捷)

 

 

3.     设计文档模板要素

依据上面提到的设计文档模板的内涵，下面的表格列出了一个典型的(面向对象)设计文档模板的基本要素：

1.        版本历史

2.        概要

3.        目录

4.        术语&符号

5.        参考

6.        提出问题

7.        分析问题

8.        测试设计

9.        逻辑设计

a)        体系结构

b)        处理逻辑

c)        关键数据结构

10.    物理设计

 

目前中国软件业的共识：

1.       设计文档，这个不强调的，但是开发过程中能没这个吗？我看大多数严格的项目不能。做个比方，诸位参加过高考吧，设计文档就是考试时候的草稿纸，你的源代码是考卷，一切以考卷上的内容为准。设计文档是可以扔掉的。有些神仙考试可以不用打草稿，有些牛人编程可以不写文档，这是一回事情。编写设计文档可以整理清楚个人的思路，风格一致的设计文档也方便团队间的交流沟通，敏捷推崇面对面的交流，这是很好的，但有时候一个图形抵过一大堆废话，有记录也有利于设计的逐步推进，不然容易反复。当然也有缺点，写文档很花时间。设计文档写到什么程度，细到什么层次，因团队实际情况，人员的能力而异，一般来说，团队成员间水平差别大就要多做些文档。设计文档是不需要和代码同步的，就像考卷不要和草稿纸同步一样。”

参考文档：Do Agile Methods Require Documentation?

2.         “和所有人类有目的的行为一样，设计是一种艺术、是一种工程、是一种带有臆测性的行为，也是一种实验性的活动。”

3.         “用来描绘源代码的图示只是设计的附属物而不是设计本身“

4.         “源代码是设计最重要的表示“

5.         “强调设计应当保持尽可能简单、适当。它是一个持续的应用(设计)原则、模式以及实践来改进软件的结构和可读性的过程。它致力于保持系统设计在任何时间都尽可能简单、干净以及富有表现力“

6.         “代码即文档(Microsoft)，建立在高度稳定的团队基础之上（这时，面对面的沟通强于文档本身）”

7.         “除非是必须马上撰写文档而且意义重大，否则的话就干脆不要写它” (Martin)

参考:On Documentation

8.         “设计文档往往是由测试优先方法指导编写的单元测试所构成的。这些单元测试都是如何使用各部分代码的鲜活的例子。其它种类的设计文档，像是类图、交互图、状态图、ER图等也可能会酌情使用”