如何书写符合标准的数据字典与详细设计文档

 

先让我们以开发过程为主线，看一看各主要文档在开发过程中的作用。首先，我们有了一个需求（当然，这个需求根据不同的实际情况，它的详细程度会有较大的出入），我们通过这个需求，对需求进行认真的分析，并出据了《需求分析说明书》。我们通过对需求的分析，可以初步总结出该需求包括几个模块，模块之间的边界，各模块的功能、系统重点、系统难点等，从而形成《概要设计》。（《概要设计》完成以后，可以开始着手进行UI设计。）通过《概要设计》与《需求分析》抽像出这个需求由哪些对象组成，每一个对象由哪些属性组成等。我们需要把对“对象”的说明进行记录，记录后形成的文档是《数据字典》。数据字典中记录某个需求包括哪些对象，这些对象包括哪些属性，每个属性的性质等内容从而形成了数据库的表结构和程序中的bean对象。然后是完成《详细设计》文档。在详细设计文档的整理过程中我们会发现更多的细节问题，这些细节会导致数据字典的变更，也有可能会导致之前已完成的部分《详细设计》文档的变更。这时，我们都应实时的对应这种变更。这也是为什么在详细设计完成之前不能进行实质性的开发的一个因素。有了详细设计后，我们就可以进行代码开发了，与此同时也可以开始进行测试用例的整理工作，从而使今后的开发与测试均源于同一个详细设计，从而使软件的测试效果在理论上得以保障。同时，在条件允许和项目需要的情况下，我们也应开发一套业务逻辑演示程序，与客户进行沟通，从而进一步提高咱们所开发出来的系统与客户的愿望的一致程度。（但，这从时间说来得急吗？等客户有了反馈后，咱们可能早就作了大量的开发工作了。这是可以解决，请往下看。）

家德瑞根据多年的经验，总结出一套尽量简单、尽量适应于更多的情形、符合国际标准的详细设计模板。用户可以根据详细设计模板进行模仿、套用。

在本文我们将重点关注数据字典与详细设计这两个文档。下面就如何编写符合家德瑞标准的数据字典与详细设计进行详细说明。

当有了《数据字典》后，家德瑞可以通过其Maker工具直接生成以“对象（即数据库中的表）”为目标的标准化程序（针对于目标对象的增、删、改、查等功能），并可以达到直接运行的程度。从而大大提升了软件开发的速度。

程序开发经历了非可视化开发到可视化开发，现在家德瑞提出了自动生成的标准化开发。有了家德瑞，程序是想出来的，而不是写出来的。

家德瑞自带的自动生成工具Maker在工程管理的标准化与软件开发的标准化的思想下可以帮助我们自动完成以下内容：

通过数据字典自动生成数据库的相关脚本

通过数据字典自动生成相关数据表的增、删、改、查等功能，并达到了生成后可以直接运行状态。

通过数据字典自动生成与标准程序相对应的详细设计文档。

通过自定义的详细设计文档生成符合实际业务流程的主干程序。

家德瑞的自动生成工具Maker可以在

http://download.csdn.net/detail/home_dear/4028211

进行免费下载。更多关于Maker工具的相关信息，可以参考《家德瑞入门教程及实例源码》（http://download.csdn.net/detail/home_dear/4029277）一文。

 

家德瑞的《数据字典》的编写是有一定的标准的，下面就将具体编写中需要注意的事项进行说明。

为了能提高大家编写数据字典的效率，家德瑞提供了一个《数据字典》样例，它是一个Maker可以识别的excel文件，我们可以进行免费下载，具体下载地址是：http://download.csdn.net/detail/home_dear/4028511。

数据字典的书写很容易，需要注意的问题有：

1、    我们应首先将项目分成几个模块，一个模块中的表放到一个数据字典中，建议一个数据字典文件的表个数不要超过30个，否则反而会将加大整体的复杂性。

2、    一个表就是数据库中的一个表，同时也是程序中的一个bean。

3、    “所有表信息”sheet面中的每一行就是一个表，注意这里的表名必须与后面的某个sheet页的名字相一致。在那个名字一致的sheet页中会具体说明这个表的属性信息。

4、    “一对一关系信息”记录表的一对一关系信息。免费下载的试用版不支持此功能。

5、    “一（多）对多关系信息” 记录表的一对多或多对多关系信息。免费下载的试用版不支持此功能。

6、    最需要注意的是表名、字段名以及与之对应的对象名、属性性、包名等的命名规则。具体命名规则在http://download.csdn.net/detail/home_dear/4029277中有详细说明。

详细设计文档的书写相对复杂一些，但也无防，家德瑞的Maker工具不仅提供了从《数据字典》转成标准化程序的功能，同时它也提供了，从《数据字典》生成标准化程序所对应的详细设计文档功能，我们可以通过Maker工具，先生成一些基本的详细设计文档，然后再在这些文档的基础上进行修改。

同时，编写符合家德瑞标准的详细设计文档，还有一个非常重要的好处，Maker工具可以认别我们手写的详细设计文档。通过详细设计文档，Maker工具可以智能的分析出所有的业务逻辑在页面上的跳转表现形式-即业务逻辑的主干程序。并且可以达到直接运行的状态。这种业务逻辑的主干程序完全可以作为上文所提到的“业务逻辑演示程序”。有了主干程序，再加上标准化程序，开发人员只要有针对性的作一些拷贝、粘贴的工作，这个项目的绝大部分工作就完成了。

好，下面看一下编写家德瑞详细设计文档的一些具体情况。

家德瑞详细设计文档的样例文档是一个Maker可以识别的excel文件，在http://download.csdn.net/detail/home_dear/4028288可以下载，也可以用Maker生成一些对象的标准化的详细设计文档以供参考。

一、  一个具体的详细设计文档，建议以模块为单位，一个模块是一个详细设计文档。一个详细设计文档中有若干个sheet页。每一个sheet页是对一个页面的功能、元素、跳转等的描述。建议一个模块以30个页面为上限，如果页面个数再多，请拆分成更细小的模块。

二、  “模块功能说明”sheet页中以文字的方式，说明这个模块的功能。这些文字请书写在excel文件的“模块功能说明”sheet页中的“A1”单元格内，如果书写在其它的单元格中将不被家德瑞的Maker所识别。我们可以对excel文件进行合并单元格、各类样式应用等操作，

三、  “页面列表”sheet面中，记录本模块的所有的页面。页面ID必须与后面的某个sheet面的名字相一致。相一致的sheet页，将对这个页面进行具体说明。页面包括两种类型：功能与显示型、仅功能型程序。“功能与显示型”是说这个页面在加载时会进行一些后台的运算，然后将运算的结果显示在页面中。例如：显示某对象的详细信息，后台的操作是以ID为条件到数据库中进行查询查询出这个对象的详细信息，然后将查询结果在页面中进行显示。“仅功能型程序”是指这个程序会在后台进行一些运算，但运算的结果没有一个具体的页面显示，例如“删除页面”，他在后台执行了一个删除操作，删除完就OK了，不需要有一个显示页面对删除的结果进行显示，可以有一个“删除是否成功”的公共页面，来显示删除的结果，当然如果我们指定了这个共公页就说明它是“功能与显示型”的了。两者的区别在于，Maker会忽略“仅功能型程序”不作处理。

四、  某个页面的具体说明页面。Sheet的名字与“页面列表”sheet页中的“页面ID”相一致。以五部分进行说明：页面功能说明、页面元素信息、页面加载动作、页面加载时扭转说明、输入参数说明等。

1、    页面功能说明

请在A2单元格内书写，可以合并单元格。

2、    页面元素信息

1)  关于title等前三项的说明

一般适用于网站类项目。不支持动态信息。如果需要动态信息，则只能是以文字的形式先说明，然后再以手工编程的方式用代码加以实现。Title是指页面的title信息。Keywords是指页面的keywords信息，一般用于页面检索。Description是指页面中的描述信息。以上三项一般用于网站类项目。可以是空

2)  什么时候需要空行？

“description：”与“整屏信息”之间需要一个空行。“区块：”与具体元素信息之间需要一个空行。除此之外不需要其它的空行。由于其第二个“整屏信息”与第一个“整屏信息”的最后一行之间也不要有空行。

3)  关于整屏信息、纵区块、区块的说明

是指一个屏幕内的信息。Maker程序对页面中的信息进行标准化展示的时候是有一定的逻辑的，这种逻辑是每一屏信息会被一个div包起来，每一个整屏信息包括多个纵屏信息，所谓的纵屏信息是指一个整屏信息被纵向分成几个区块。

整屏信息表示一个100%宽的整个区域，是页面中的第一层div。“纵区块信息”表示整屏div下左右分成几个部分的div，如果分一个部分则宽度肯定是100%，一个整屏中可以有多个“纵区块”多个“纵区块”共同来横向填充满整个“整屏”，一个纵区块可以有多个“区块”，多个区块在纵向上填充满整个“纵区块”。

整屏信息、纵区块信息中的“英文名”一项用于div的ID。“纵区块信息”与“区块：”都有“宽度”一项，其中“区块：”中的宽度已费除，没有作用了。纵区块信息中的宽度有用，用于标识这个纵区块占页面整体的宽度比例，系统支持100%、50%、30%如果是100%说明只有一个纵区块，这一个纵区块横向填满整屏。纵区块内横向可以有6列信息。50%说明一屏中有两个纵区块，每个纵区块内横向可以有2列信息。30%说明一屏中可以三个纵区块，每个纵区块内可以1列信息。

“区块：”中有“类型”一项，其意义是这个区块的类型，可以三个选择。“form”说明这个区块会被form标签包围；“显示”则区块信息用于显示，如对象的详细页面。“循环”区块信息会被循环显示10次，如列表页面。“区块名是否显示”是指区块都有一个名字，如果显示则会在区块的头部显示一个本区块的名字。

4)  关于元素的说明

元素可以与某个表相对应，从而生成后的标签会是hdr标签。而且这种情况下生成的标签会与标准化程序相对应。如果“表名”一项中有内容，说明这个元素是与某个表对应的，如果这项是空的说明这个元素与表无关。只是说明信息文字。如果与表对应了，则元素名必须与该表的某个字段名相对应，注意这里所用到均为表名、字段名而非对象名、属性名。注意家德瑞的命名规则。如果“默认值”内有内容则该项将以“默认值”中的值进行显示，否则将统一显示为“信息数据”。元素类型包括很多，这里不再多说，但最好是用家德瑞提供的模板进行编写，因为模板或样例中的“类型”一项都是下拉框，这样我们不会写错。“事件”包括很多，这里不再多说，但最好是用家德瑞提供的模板进行编写，因为模板或样例中的“事件”一项都是下拉框，这样我们不会写错。“连接目标”如果是连接则会另开窗口打开。

3、    页面加载动作

以文字的方式说明页面的动作。这里的业务逻辑将是今后手工开发的重要内容。最好写在“AA2”单元格内。可以合并单元格。

4、    页面加载时扭转说明

这是一个重点内容，根据不同的业务要求，每一个页面在根据不同的实际情况转到下一个页面。最终完成整个业务逻辑。在这里我们需要写好本页面在哪些情况下，会转到哪些页面去继续后面的业务逻辑。这部分内容会被家德瑞的Maker程序所识别，如果跳转个数多于一个时会出现一个叫作“家德瑞暗示框”的东西，来完成这些工作。具体是如何实现的，请下载Maker自己体验吧。这种体验真的很美妙。

5、    输入参数说明

输入参数与页面元素信息共同组成对页面的输入与输出的说明。同时也在说明着这个页面的内、外部接口信息。

说明：

生成过程较为复杂，如果出现错误，可以尝试从启tomcat，并删除已生成的excel标准化详细设计文档。然后从新生成。

作者还有过另一篇文章：《详细设计在软件开发中的作用 》http://blog.csdn.net/home_dear/article/details/7219177