第二章 文档

​软件文档的编制在软件开发工作中占有突出的地位和相当的工作量。具体来讲,文档一方面充当了各个开发阶段之间的桥梁,作为前一阶段的工作成果及结束标志,它使分析有条不紊地过渡到设计,再使设计的成果物化为软件。

​ 另一方面,文档在团队的开发中起到了重要的协调作用。随着科学技术的发展,现在几乎所有的软件开发都需要一个团队的力量。团队成员之间的协调与配合不能光靠口头的交流,而是要靠编制规范的文档。它告诉每个成员应该做什么,不应该做什么,应该按着怎样的要求去做,以及要遵守哪些规范。此外,还有一些与用户打交道的文档成为用户使用软件产品时最得力的助手。

合格的软件工程文档应该具备以下几个特性。

  1. 及时性。在一个阶段的工作完成后,此阶段的相关文档应该及时地完成,而且开发人员应该根据工作的变更及时更改文档,保证文档是最新的。可以说,文档的组织和编写是不断细化、不断修改、不断完善的过程。

  2. 完整性。应该按有关标准或规范,将软件各个阶段的工作成果写入有关文档,极力防止丢失一些重要的技术细节而造成源代码与文档不一致的情况出现,从而影响文档的使用价值。

  3. 实用性。文档的描述应该采用文字、图形等多种方式,语言准确、简洁、清晰、易懂。

  4. 规范性。文档编写人员应该按有关规定采用统一的书写格式,包括各类图形、符号等的约定。此外,文档还应该具有连续性、一致性和可追溯性。

  5. 结构化。文档应该具有非常清晰的结构,内容上脉络要清楚,形式上要遵守标准,让人易读、易理解。

  6. 简洁性。切忌无意义地扩充文档,内容才是第一位的。充实的文档在于用简练的语言,深刻而全面地对问题展开论述,而不在于文档的字数多少。总体上说,软件工程文档可以分为用户文档、开发文档和管理文档三类,如表14.1所示。

软件文档的分类
Figure: 软件文档的分类

下面是对几个重要文档的说明。

  1. 可行性研究报告:说明该软件开发项目的实现在技术上、经济上和社会因素上的可行性,评述为了合理地达到开发目标可供选择的各种可能实施的方案。

  2. 项目开发计划:为软件项目实施方案制定出的具体计划,应该包括各项工作的负责人员、开发的进度、开发经费的预算、所需的硬件及软件资源等。

  3. 软件需求规格说明书:也称软件规格说明书,是对所开发软件的功能、性能、用户界面及运行环境等做出的详细的说明。

  4. 概要设计说明书:是概要设计阶段的工作成果,它应说明功能分配、模块划分、程序的总体结构、输入/输出以及接口设计、运行设计、数据结构设计和出错处理设计等,为详细设计奠定基础。

  5. 详细设计说明书:重点描述每一模块是怎样实现的,包括实现算法、逻辑流程等。

  6. 用户手册:详细描述软件的功能、性能和用户界面,使用户了解如何使用该软件。[2]

  7. 测试计划:为组织测试制定的实施计划,包括测试的内容、进度、条件、人员、测试用例的选取原则、测试结果允许的偏差范围等。[2]

  8. 测试分析报告:是在测试工作完成以后提交的测试计划执行情况的说明。对测试结果加以分析,并提出测试的结论意见。[2]

[1] 张海藩;吕云翔;编著.软件工程(第4版)

[2] 该部分暂不考虑

results matching ""

    No results matching ""