互联网产品设计进阶（8）读别人的详细设计说明书

唐杨烱．唐昭武校尉曹君神道碑有这样的记载：“托无愧之铭，跋涉载劳於千仞，访他山之石，东西向逾万里。”诚所谓：它山之石，可以攻玉。

 

一、关于详细设计说明书

最近在准备一个项目的详细设计说明书。编制详细设计说明书的目的，在于说明一个软件系统各个层次中的每一个程序 （每个模块或子程序）的设计。详细设计基于需求调研分析成果和概要设计成果编制，是系统开发、测试、验收等项目过程的重要指导文件。也不难理解，为什么在电视剧生产量最大的中国，很多导演或演员总会叹息：没有好本子。确实，一个好本子，可以让一个名不见经传的演员一炮走红；一个垃圾本子，则可能让一个很红的实力派演员被人称为奶油小生。

自然，也就会归结到我们的系列话题：互联网产品设计。详细设计说明书用来指导设计人员、开发人员、工程人员、测试人员更好地完成相关工作。文档的颗粒度越高，越有利于直接指导开发人员进行实现。

详细设计是考验技术专家设计思维的重要关卡，详细设计说明书应当把具体的模块以最“干净”的方式（黑箱结构）提供给编码者，使得系统整体模块化达到最大。一份好的详细设计说明书，可以使编码的复杂性减低到最低，实际上，严格的讲详细设计说明书应当把每个函数的每个参数的定义都精精细细的提供出来，从需求分析到概要设计到完成详细设计说明书，一个软件项目就应当说完成了一半了。换言之，一个大型软件系统在完成了一半的时候，其实还没有开始一行代码工作。当然，“胸中有丘壑”者例外。

做产品设计之前，可以在浏览器中输入http://file.baidu.com，在出现的浏览器界面中，再输入“详细设计说明书”，你会有许多意想不到的收获，没准你会轻松理解某个大型社区的详细设计。

一个典型的参考目录

这是一个典型的参考目录。

1. 综述... 4

1.1. 文档说明... 4

1.2. 编写目的... 4

1.3. 适用范围... 4

1.4. 名词、术语、缩略语定义... 5

1.5. 参考资料... 5

2. 项目概述... 5

2.1 项目背景... 5

2.2 项目名称... 6

2.3 项目单位... 6

2.4 项目目标... 6

3. 任务概述... 7

3.1 设计目标... 7

3.2 系统环境... 7

3.3 需求概述... 7

3.4 条件与限制... 8

3.5 详细设计的基本任务... 9

4. 总体设计... 9

4.1 设计方法论... 9

4.2 系统总体结构... 9

4.3 逻辑架构... 9

4.4 软件架构... 9

4.5 部署结构... 10

5. 功能设计... 10

5.1 功能划分... 10

5.2 子系统名称A.. 11

5.3 子系统名称B. 12

6. 级联设计... 13

6.1 系统级联概述... 13

6.2 级联应用场景... 13

6.3 级联设计方案... 13

7. 栏目与页面设计... 13

7.1 桌面栏目设计... 13

7.2 系统页面设计... 13

8. 外部接口设计... 14

8.1 平台内部接口... 14

8.2 第三方产品接口... 14

8.3 业务应用系统接口... 14

9. 程序结构描述... 15

9.1 程序目录结构... 15

9.2 代码目录规则... 15

9.3 数据命名规范... 15

10. 异常处理机制... 15

三、简明扼要的书写

说明书确实要尽量全，但不能因为“全”而忽略了条理性。篇幅所限，这里列举一个比较直观的实例。

为了说明“学生信息查询模块”，可以遵循以下步骤。

第一，功能流程图。如下图所示。

第二，功能描述。如下所示。

（1） 功能类型：查询数据

（2） 功能概述：显示查询结果

（3） 前提业务：无

（4） 后继业务：

（5） 功能约束：没有约束；

（6） 约束描述：

（7） 操作权限：面向所有用户

第三，界面中的动作说明，如下所示。

动作编号	动作名称	动作描述
A01	确定	点击按钮 提交数据到图书查询数据处理.jsp页面
A02	图书信息查询	点击按钮 将页面转至图书信息查询.jsp页面

第四，模块内部逻辑，如下所示。

01. Search.jsp用于显示界面的内容，给用户显示一个查询接口

02. Index.jsp用来调度所有的页面，它根据传入的参数来决定包含哪一个jsp页面来显示内容；

在index.jsp页面中，

它根据传入的参数来决定包含哪一个jsp页面来显示内容；则可以通过<jsp:include page=”<%= ……%>”/>,利用jsp:include标签来被动态加载发送到相应页面；

03. List.jsp 用来显示查询到的结果列表。

04. View.jsp用来显示查询到的学生的各项属性。

第五，存储分配。以学生文件为例。

序号	字段	字段名	类型	长度	精度	小数位数	默认值	允许空	主键	说明
1	XSID	学生编号	Int	10			1		√	自动编号
2	Name	姓名	nvarchar	10
3	Sex	性别	nvarchar	2				√
4	ZJH	证件号码	nvarchar	25				√
5	LXDH	联系电话	nvarchar	40				√
6	DJRQ	登记日期	datetime	8				√
7	YXQZ	有效期至	datetime	8				√
8	YJSS	已借书数	smallint	2				√
9	RuleID	学生规则ID	int	10
10	ZT	是否挂失	nvarchar	2				√

参考资料：http://file.baidu.com