关于GJB438A-97软件设计文档的疑问

关于GJB438A-97软件设计文档的疑问

 

[摘要] 本文记录了对GJB438A-97《武器系统软件开发文档》的软件设计文档的一些疑问。

 

1           引言

　　GJB438A-97《武器系统软件开发文档》规定了软件设计文档编制的格式、内容和要求。在工程实践中执行该标准时，感到其中有些要求比较难于理解和实施。

GJB438A-97是与GJB2786-96《武器系统软件开发》配套的标准。GJB2786-96的编制参照采用了DoD-STD-2167A。

　　查阅了DoD-STD-2167A中关于软件设计文档的原文，发现GJB438A-97也源于DoD-STD-2167A，但与原文有些差异。下面简要记录关于软件设计文档编这些差异和疑问。

2           标识

　　GJB438A-97规定软件设计文档的1.1节是“标识”。 对该节的要求是：

　　“列出本文档的：

a.    已批准的标识号；

b.   标题；

c.    缩略语；

d.   本文档适用的系统和计算机软件配置项(CSCI)，并标识派生该CSCI更高层的规格说明。”

　　上述要求使我们把“已批准的标识号”理解为软件设计文档的标识号，把“缩略语”理解为软件设计文档中使用的所有缩略语，从而把整个缩略语表都放在了1.1节中。

　　DoD-STD-2167A DID SDD中关于“标识”的原文是：

　　“This paragraph shall be numbered 1.1 and shall contain the approved identification number, title, and abbreviation, if applicable, of the CSCI and the system to which it this SDD applies.   This paragraph shall identify the higher-level specification(s) containing the requirements from which the design of this CSCI was derived.”

　　从原文中可看出：

a.    “已批准的标识号”是指CSCI的标识号；

b.   “缩略语” 是指CSCI的名称中用到的缩略语；

　　如果某个设计文档中的所有缩略语有多页，放在1.1节中好象不太合适。

 

3           CSC的概要设计说明

　　GJB438A-97关于CSC的概要设计说明有如下要求：

　　“各节应提供以下信息：

a.    标识由需求规格说明分配给CSC的需求。如果CSC是由下一级的一些CSC组成的，则可以引用下一级的CSC描述部分信息或全部信息；

b.   利用执行控制流和数据流来描述CSC的概要设计。如果CSC是由下一级的一些CSC组成，应标识下一级各CSC之间的相互关系。另外，应在软件需求规格说明规定中标识每个CSCI的内部接口。这些内部接口应由CSC和它的下一级CSC定位；

c.    描述CSC的设计需求和设计约束，如果CSC是由下一级的一些CSC组成，则可引用下一级CSC的部分信息和全部信息。”

　　对以上描述有如下疑问：

a.    “标识由需求规格说明分配给CSC的需求”，需求规格说明还没有涉及CSC，怎么能对CSC分配需求？

b.   “应在软件需求规格说明文档中标识每个CSCI的内部接口”，这里说的是设计文档，怎么又对软件需求规格说明文档提出了要求？

c.    “内部接口应由CSC和它的下一级CSC定位”，“ 定位”的含义是什么？

d.   在“则可以引用下一级的CSC描述部分信息或全部信息”与“则可引用下一级的CSC的部分信息和全部信息”中，为何前一句用“或”，后一句用“和”？

 

　　DoD-STD-2167A DID SDD中与上述要求对应的原文是：

　　This subparagraph shall provide the following information:

a.    Identify the requirements allocated to the CSC from the applicable requirements specification(s). If the CSC is composed of sub-level CSCs, some or all of this information may be referenced and provided by the sub-level CSC description.

b.   Describe the preliminary design of the CSC in terms of execution control and data flow. If a CSC is composed of sublevel CSCs, this description shall identify each CSCI internal interface documented in the Software Requirements Specification, that is to be addressed by the CSC and its sub-level CSCs, as applicable. This information may be referenced rather than duplicated for each sub-level CSC.

c.    Identify the derived design requirements for the CSC and any design constraints imposed on or by the CSC. If the CSC is composed of sub-level CSCs, some or all of this information may be referenced and provided by the sub-level CSC description.

 

　　根据原文，似乎要这样理解：

a.    根据适用的需求规格说明标识分配给该CSC的软件需求。如果CSC由下一级的一些CSC组成，这部分内容可全部或部分地由下一级的CSC提供；

b.   利用执行控制流和数据流来描述CSC的概要设计。如果CSC由下一级的一些CSC组成，应指明由该CSC及其下一级CSC处理的软件需求规格说明中规定的CSCI内部接口。下一级CSC的描述可引用这些内容而不必复述；

c.    标识对该CSC衍生的设计要求和设计约束，以及由该CSC提出的设计约束。如果CSC由下一级的一些CSC组成，这部分内容可全部或部分地由下一级的CSC提供。

 

4           下一级CSC的概要设计说明

　　GJB438A-97对下一级CSC的概要设计说明有如下规定：

　　“从3.2.1.1节开始编号，标识下一级的CSC的名称和项目唯一标识号及其用途，以及提供3.2.X中c项所需要的信息。”

　　对以上描述有如下疑问：

　　3.2.X节要提供CSC的a、b、c三项信息，为什么对下一级CSC只要求提供c项信息？

　　根据原文“provide the information required by a through c above”，上述描述似乎要改为“提供3.2.X中从a到c项所需要的信息”。

5           设计要求及约束

　　GJB438A-97规定软件设计文档的第4.X.Y.1的标题是“（CSU的名称）的设计及约束”， 第4.X.Y.2的标题是“（CSU的名称）的设计”。两节的标题中都有设计。根据DoD-STD-2167A DID SDD的原文，第4.X.Y.1的标题似乎要改为“（CSU的名称）的设计要求及约束”。

 

6           编程语言和库

　　GJB438A-97关于编程语言和库有如下要求：

　　“如果CSU不是用CSCI规定语言编写，那么要标识这一程序语言，并且阐述使用该语言的基本原理。如果CSU保存在库中，则各节要标识库的名称和项目唯一的标识号以及描述该库的设计文档。”

　　DoD-STD-2167A DID SDD中与上述要求对应的原文是：

　　“If the CSU is to be coded in a programming language other than the specified CSCI language, the programming language shall be identified and the rationale for its use shall be provided. If the CSU resides in a library, this subparagraph shall identify the library by name and project unique identifier, and the design document in which the library description can be found.”

　　根据原文，似乎要这样理解：

　　“如果CSU的编程不使用为CSCI指定的编程语言，那么应指明该编程语言，并且阐述使用该编程语言的理由。如果CSU是一个库单元，则应在此指明库的名称和项目唯一的标识号以及可找到的描述该库的设计文档。”

 

7           逻辑流程

　　GJB438A-97关于逻辑流程的描述有如下要求：

　　“h. 逻辑流程图。根据a到g项描述CSU的逻辑流程，并描述CSU执行时初始化的条件、调用的通信接口的特征以及其它CSU控制条件。若在CSCI的操作期间序列是被动态的控制，则应描述控制的方法和该方法的逻辑和输入条件，例如时间变化、优先级赋值、诸如输入/输出、内部存储器数据传送的内部操作、离散输入信号的读出以及与CSCI的中断操作的时间关系；”

　　对以上描述有如下疑问：

a.    “逻辑流程图”，从后面的要求中看不出一定要用“图”来描述；

b.   “其它CSU控制条件”为何要在这里描述？

c.    “优先级赋值”是什么含义？

d.   “与CSCI的中断操作的时间关系” 是什么含义？

 

　　DoD-STD-2167A DID SDD中与上述要求对应的原文是：

　　 “Logic flow. Describe the logic flow of the CSU in terms of the above items. Describe the conditions under which CSU execution is initiated and, if applicable, communication interface features are invoked, and the conditions under which control is passed to other CSUs, as applicable.  If sequencing is dynamically controlled during the CSCI's operations, the method for sequence control and the logic and input conditions of that method shall be describe, such as timing variations, priority assignments, internal operations such as data transfer in and out of internal memory, sensing of discrete input signals, and timing relationships between operations with the CSCI.”

　　根据原文，似乎要这样理解：

　　“h. 逻辑流程。根据a到g项内容描述CSU的逻辑流程。要描述启动CSU执行的条件、被激活的通信接口功能（如果有）、把控制传给其它CSU的条件等。如果在CSCI的操作期间，执行顺序是动态控制的，则应描述顺序控制的方法以及该方法的逻辑和输入条件，如定时变更、优先级分配、诸如内部存储器的数据移入移出那样的内部操作、离散输入信号的判读以及CSCI各种操作之间的定时关系。”

 

8           CSCI数据

　　GJB438A-97关于CSCI数据的描述有如下要求：

　　“为便于可读和易维护，可用一个或几个表提供如下信息，这些信息可提供给所有的数据元素。”

　　最后一句“这些信息可提供给所有的数据元素”令人费解。根据原文：

　　“For ease in readability and maintenance, the information required below be provided in one or more tables. The following information shall be provided for each data element, as applicable；”

　　原来最后一句的意思是“对每一个数据元素都要按以下适用的项目来描述：”

 

　　GJB438A-97关于CSCI内部数据有如下描述：

　　“（12）数据元素的CSU的项目唯一标识号；”

　　对照原文“The CSU project unique identifier(s) where the data element is used”，似乎要理解为“使用该数据元素的CSU的项目唯一标识号；”

 

9           数据文件与CSC/CSU的交叉索引

　　GJB438A-97规定软件设计文档第6.1节的标题是“CSC/CSU数据文件的交叉引用”。根据原文“Data file to CSC/CSU cross reference”，似乎要理解为“数据文件与CSC/CSU的交叉索引”。

 

10       需求可追踪性

　　GJB438A-97关于需求可追踪性有如下要求：

　　“应提供分配给每个CSC的上一级CSU，可追溯到软件需求规格说明和接口需求规格说明要求的需求。”

　　“每个CSC的上一级CSU”显然是不成立的。

　　DoD-STD-2167A DID SDD中对应的原文是：

　　“This section shall be numbered 7 and shall provide traceability of the requirements allocated down to the CSU level of each CSC back to the requirements of the Software Requirements Specification and Interface Requirements Specification.”

　　这似乎要理解为：

“本章应描述每个CSC中，一直到CSU这一级与软件需求规格说明和接口需求规格说明相互之间的可追踪性。”

 

 

后记

本文素材记于2002年。GJB438A-97现在仍然是有关项目必须遵循的标准之一。

2009年5月31日