SJ T 11291 2003 面向对象的软件系统建模规范 第三部分：文档编制

 

    SJ/T 11291-2003

                   面向对象的软件系统建模规范

                         第三部分：文档编制

1         范围

     本标准规定了对面向对象的软件系统建模过程中所生成的文档的编制要求，并给出了编制提示。本部分适用于软件系统的分析和设计，也可用于编程、测试、评估和维护。

2         引用标准

     下列文件中的条款通过本标准的引用而成为本标准的条款。凡是注日期的引用文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本部分，然而，鼓励根据本部分达成协议的各方研究是否可使用这些文件的最新版本。凡是不注日期的引用文件，其最新版本适用于本部分。

     SJ/T111290-2003 面向对象的软件系统建模规范  第1部分：概念与表示法

     SJ/TXXXX-XXXX 面向对象的软件系统建模规范 第2部分：过程指导

3         文档的编制要求

      在一个面向对象的软件系统建模中，一般地说，应产生下列文档：

      总体说明文档：

      用况图文档：

      类图文档：

      顺序图文档：

      协作图文档：

      状态图文档：

      活动图文档：

      构件图文档：

      部署图文档：

      其中有的文档有时会引入包图来管理信息组织的复杂性

      开发者也可根据所承担项目的实际情况，灵活取舍。

      当开发者按照《面向对象的软件系统建模规范  第2部分：过程指导》开发软件系统时，可以按开发阶段组织文档，分别形成：

      需求定义文档、分析文档和设计文档。

      其中每种文档的内容包含一个或多个上面提到的各种图的文档，具体的要求见《面向对象的软件系统建模规范  第2部分：过程指导》

4         文档的编写提示

4.1        总体说明文档

以文本方式，对整个系统做一些必要的说明。内容包括系统的目标、意义、应用范围、项目背景和文档组成等。但不必对系统的总体进行详细地说明，只需作提纲挈领式的简单介绍。另外，还要说明系统的建模文档由那几种具体的文档组成、每种文档的份数以及对各种文档的组织等。

4.2        用况图文档

4.2.1图形文档

     即所绘制的用况图

4.2.2文字说明

     用况图文档由以下部分组成：用框图综述、参与者描述、用况描述、用框图种元素间的关系描述和其他与用框图有关的说明。

4.2.2.1 用况图综述

       从总体上阐述整个用框图的目的、结构、功能以及组织。以文字描述文档所包含的部分。

4.2.2.2 参与者描述

     列出一个用况图中的每个参与者的名称，可按字母顺序或其他某种有规律的次序排列。必要时要对参与者附有必要的文字说明，也可以说明他所涉及到的用况和交互图的名称。

4.2.2.3用况描述

     对于一个用框图中的每个用况，记录如下的信息。要按某种顺序排列他们。

（a）       名称

用每个用况有一个在图内唯一的名字，并且改名字要反映出它所描述的功能。书写位置是在用况描述的第一行。

（b）       行为描述

用自然语言分别描述参与者的行为和系统行为，建议把参与者的行为靠左对齐书写，把系统行为靠较右的位置对其书写。

在描述较复杂的含有循环或条件分支的行为时，可使用一些结构化编程语言的控制语句，如while，for，if-then-else等。

当要表明控制语句的作用范围时，可使用括号，如{、}或begin、end等，也可以使用标号以便更清楚地表示控制走向。

如有必要，可使用顺序图。状态图或协作图描述参与者的行为和系统行为。

（c）       用况图中元素间的关系描述

产生一份描述用况图中的参与者与用况间、用况间以及参与者见关系的文字性描述文档。具体的有下面几部分构成。：

1）  关系的名称：

2）  关系的类型：关联，泛化，包含，扩展：

3）  关系所涉及的类目：对关系所连接的类目应指明名称和类型（参与者或用况）。

（d）       其他与用况图有关的说明

与该用况图有关的但上面文档中没有涉及的其他信息的描述。

4.3类图文档

4.3.1 图形文档

   即所绘制的类图。

4.3.2 文字说明

   文字描述有以下部分组成：类图综述、类描述、关联描述、泛化描述、依赖描述和其他与类图有关的说明。在实际使用时，这些部分是可选的。

4.3.2.1 类图综述

   从总体上阐述整个类图的目的、结构、功能及组织。文字描述文档所包含的部分。

4.3.2.2 类描述

   类描述包括类整体说明、属性说明、服务说明、关联说明、泛化说明、依赖说明及其他说明。

a)       类的整体说明

对整个类及其对象的情况加以说明，内容包括：

1）  类名：应是中文名或英文名；

2）  解释：对类的责任的文字描述；

3）  一般类：描述该类的实例的状态图的名称列表；

4）  状态转换图：描述该类的实例的状态图的名称列表；

5）  主动性：有无中动性；

6）  永久性：有无永久性；

7）  引用情况：若此类为其他类图所定义，则要表明他所属于德类图；若此类被其他类图引用则要表明所引用的类图；

8）  多重性

9）  其他：：是否有特别的数据完整性或安全性要求等。

b)      属性说明

逐个的说明类的属性。每个属性的详细说明包括以下内容：

1）  属性名：中文属性名或英文属性名：

2）  多重性：该属性的多重性；

3）  解释：该属性的作用；

4）  数据类型；

5）  聚合关系：如果这个属性的作用是为了说明聚合关系，则在这里说明这种关系；

6）  组合关系：如果这个属性的作用是为了说明组合关系，则在这里说明这种关系；

7）  关联关系：如果这个属性是为了实现该类的对象和其他对象之间的链而设置的，则在这里明确的说明这一点；

8）  实现要求：该属性的取值范围、精度、初始值及其他描述。

c)      服务说明

逐个的说明类中的每个服务。每个服务的详细说明包括以下内容：

1）  服务名：中文服务名或英文服务名；

2）  主动性：有无主动性

3）  多态性：有无多态性；

4）  解释：该服务的作用；

5）  服务的活动图：详细描述活动具体细节的活动图的名称列表；

6）  约束条件及其他：若该服务的执行有前置条件、后置条件或执行时间的要求等其他需要说明的事项，则在此说明。

d)      关联

描述该类所涉及的所有的关联，每个与该类相关的关联有关联名。

e)       泛化

描述该类所涉及的所有的泛化，每个与该类相关的关联有关联名。

f)       依赖

   描述该类所涉及的所有依赖，每个与该类相关的关联有关联名。

4.3.2.3 关联描述

   类图中的每一关联都应有如下的描述：

a）  关联名称：中文关联名或英文关联名；

b）  关联的类型：应是一般二元关联，聚合，组合，多元关联，自关联，限定关联，导出关联，其他关联；

c）  关联所连接的类：按照一定顺序列举出关联所连接的类；

d）  关联端点：对每一个关联端点描述如下；

1）  导航性：是否有导航性；

2）  排序：是否排序；

3）  聚合：是否有聚合，如果有，则要指明是聚合还是组合；

4）  多重性；

5）  可变性：应是无。只增加、冻结；

6）  角色：角色名用中文名和英文名表示均可。

7）  可见性：用+、—、#表示。

8）  接口说明符

4.3.2.4 泛化描述

类图中的每一个泛化都有如下的描述：

a）  泛化关系中的父类；

b）  泛化关系中的子类；

c）  泛化关系中的区分器；

d）  泛化关系中的限制符：应是完全、不完全、重叠和不相交。

4.3.2.5 依赖描述

类图中的每一个泛化都有如下的描述：

a）  依赖名称；

b）  依赖所涉及的类的名称；

c）  依赖的类型；

d）  依赖的附加说明。

4.3.2.6 其他描述文档

与该类图有关的但上面文档中没有涉及的其他信息的描述。

4.4顺序图文档

4.4.1图形文档

     即所绘制的顺序图。

4.4.2文字说明

     顺序图的文字说明文档应包含：顺序图综述、顺序图中的对象与参与者描述、对象接收/发送信息的描述和其他与顺序图有关的说明。

4.4.2.1顺序图综述

     从总体上描述该顺序图的目的，以及所涉及的对象和参与者。

4.4.2.2 顺序图中的所有的对象和参与者，一次进行如下的描述：

a）对象类型：是参与者还是类；

b）对象名称；

c）是否为主动对象；是或否，此描述针对对象而言，对于参与者不应有此描述；

d）其他与对象或参与者有关的信息。

4.4.2.3 对象接收发送信息的描述

对顺序图中的每一个对象或参与者，详细的描述其接收/发送信息的类型、时序及其他信息之间的触发关系。对每一个对象 和参与者应按照时间顺序分别列出该对象或参与者所接收/发送的全部消息。对每一条信息应包含下面的内容：

a）  消息名称；

b）  是发送消息还是接收消息

c）  消息的类型；

d）  若为接收消息，应列出该消息所直接触发的消息的名称列表；

e）  是否为自接收消息；

f）   消息的发送对象名称；

g）  消息的接收对象名称。

4.4.2.4 其他与顺序图有关的说明

与顺序图有关的补充信息。

4.5 协作图文档

4.5.1图形文档

      即所绘制的协作图。

4.5.2文字说明

协作图的文字说明应包含下列部分：协作图的综述、协作图中的对象或角色描述、对象或角色接收/发送信息的描述、对象或角色间的链描述和其他与下作图有关的说明。

4.5.2.1 协作图综述

从总体上描述该协作图的目的以及其所涉及的对象或类元角色。

4.5.2.2 协作图中的对象或角色描述

对协作图中的所有类元角色或对象，一次列出下面的各项：

a)       名称；

b)      类型：类元角色或对象；

c)      是否为主动对象或角色：是或否；

d)      其他与类元对象有关的信息。

4.5.2.3 对象或角色接收/发送信息的描述

对协作图中的每一个类目角色或实例，详细的描述其接收/发送消息的类型及时序、以及与其他消息的触发关系。每一类目角色或实例应有下列描述：

a）  对象或角色名称；

b）  列出该对象所接受/发送的全部小溪流，对每一条信息应包含下面的信息。

1）  消息名称；

2）  消息的格式：参见概念和表述发部分；

3）  是发送消息还是接收消息；

4）  消息类型；

5）  若为接收消息应列出该消息所直接触发的消息序列；

6）  是否为自接收消息；

7）  消息的发送类目角色或实例

8）  消息的接收类目角色或实例。

4.5.2.4 对象或角色间的链描述

对象间或角色间的链应由下面的成分构成：

a）  链名称；

b）  链所连接的角色或对象的名称；

c）  链上的角色名，每个角色应包含下列信息：

1）  角色名：中文名或英文名；

2）  可见性：+、—、或#

3）  特殊的衍型：global、local、parameter、self、vote、broadcast；

d）  其他与链有关的信息。

4.5.2.5 其他与协作图有关的说明

与协作图有关的补充信息。

4.6 状态图文档

4.6.1图形文档

   即所绘制的状态图。

4.6.2.状态说明

   状态图的文字说明应包含：状态图综述、状态图的状态描述、状态图的转换描述和其他的状态图有关的说明。

4.6.2.1状态图综述

   从总体上，该状态图描述一个对象在外不吉利的作用下进行的状态变迁、所涉及到的状态和转换以及设置该状态图的目的等。

4.6.2.2 状态图的状态描述

   描述一个状态图的所有的状态，对每一个具体状态应包括以下各项：

a）  状态的名称：中文名或英文名；

b）  状态的类型：简单状态、兵法组合状态，顺序组合状态，子状态，初始伪状态，终状态，结合状态，历史状态，引用状态，桩状态，同步状态；

c）  入口动作；

d）  出口动作；

e）  内部转换：有一系列的内部转换项组成。每个部分转换项有下列格式：动作标号/动作表达式；

f）   若为组合状态应列举出其所包含的子状态；

g）  其他与该状态有关的信息。

4.6.2.3 状态图的转换描述

   本文档用来描述一个状态图的所有的状态转换，每一个具体转换应包括以下各项；

a）  转换的源状态；

b）  转换的目标状态；

c）  转换串：时间特征标记‘[’监护条件‘]’‘/’动作表达式；

d）  转换中的分支：同步条、结合点、动态选择点。

4.6.2.4 其他与状态图有关的说明

   与状态图有关的补充信息。

4.7活动图文档

4.7.1图形文档

   即所绘制的活动图。

4.7．2文字说明

   活动图的文字说明包含：活动图综述、活动图中的动作状态描述、活动图中的转换描述和其他与活动图有关的说明。

4.7.2.1 活动图综述

   从总体上，活动图描述一个对象的一个操作的活动序列，或者是多个对象为完成某一个目的而进行的协作所涉及的活动序列，以及设置该活动图的目的等。若活动图用于描述系统的其他目的，也按本格式描述。

4.7.2.2 活动图中的动作状态描述

   本文东用来描述一个活动图的所有的动作状态，每个具体动作状态包括以下内容：

a）  名称：中文名或英文名；

b）  类型：一般动作状态，子动作状态，信号发送，信号接收，初始伪动作状态，终动作状态，历史状态；

c）  入口转换；

d）  出口转换；

e）  活动伪码；

f）   其它与该状态有关的信息。

4.7.2.3 活动图中的转换描述

   本文档用来描述一个活动图的所有的转换，每一个具体转换包括一下内容：

a）  转换的名称；

b）  源动作状态；

c）  终动作状态；

d）  转换中的分支：包括分叉、同步条、决策和合并：

e）  转换中的控制分叉：包括控制分叉的名称，与分叉相脸的入口和出口元素的名称。

4.7.2.4 其它与状态图有关的说明

   与状态图有关的补充信息，如泳道的划分、对象流、信号发送和信号接收等信息。

4.8 构件图文档

4.8.1图形文档

即所绘制的构件图。

4.8.2文字说明

构件图的文字说明文档包含：构件图综述、构件图中的构件描述、构件图中的关系描述和其他与构件图有关的说明。

4.8.2.1构件图的综述

从总体上，构件图描述构件间的依赖关系、设置该构件图的目的等。

4.8.2.2 构件图中的构件描述

构件图中的每一个构件包含下列描述：

a）  构件名称

b）  构件的接口；

c）  构件所涉及的关系；

d）  在逻辑上构件所实现的类；

e）  构件的类型。

4.8.2.3 构件图中的关系描述

a）关系的名称；

b）关系的起始构件的名称

c）关系的结束构件名称；

d）关系的类型：实现依赖、使用依赖或其他依赖。

4.8.2.4 其他与构件图有关的说明

其他与构件图有关的信息。

4.9 部署图文档

4.9.1图形文档

   即所绘制的部署图。

4.9.2文字说明

   部署图的文字说明文档包含：部署图综述、部署图中的节点描述、部署图中的关系描述和其他的部署图有关的说明。

4.9.2.1 部署图综述

   从总体上描述部署图的目的以及节点之间的相互关系等。

4.9.2.2 部署图中的节点描述

   对部署图中的每一个节点包含下列描述：

a)       节点名称；

b)      节点中的构件实例；

c)      节点所涉及的链的名称；

d)      节点的类型。

4.9.2.3 部署图中的关系描述

   a)关系的名称；

   b）关系的起始节点（或构件）的名称；

   c）关系的结束节点（或构件）的名称；

d）关系的类型：实现依赖、使用依赖、其他依赖或通讯链。

4.9.2.4其他与部署图有关的说明

     其他与部署图有关的信息。

4.10 包图文档

为了管理模型的信息租者的复杂性，在比较复杂的模型中，通常将关系联系比较密切的图形元素划分到一个包里面。最常见的是在用况图和类图中使用包图。一般情况下，包图与前面提到的几种图搭配使用，而不单独使用。

4.10.1图形文档

即所绘制的包图。

4.10.2文字说明

包图的文字说明文档包含：包图的综述、包图中的包描述和其他与包图有关的说明。

4.10.2.1包图的综述

从总体上描述包图的名称、目的以及与其他包的相互关系等。

4.10.2.2包图中的包描述

包图中的每一个包包含下列描述：

a）  包的名称；

b）  包的种类：类包、用况包或其他；

c）  详细描述该包所包含的建模元素所在的文档；

d）  与该包有关系的其他包，应包括如下信息：

1）  包的名称；

2）  与该包的关系：依赖（访问和移入）、泛化，要注明方向性。

4.10.2.3. 其他与包图有关的说明

其他与包图有关的信息。

                           附录A

                       （资料性附录）

                       文档编写样式

A．1文档的封面格式

文档的封面格式如下：

 

1676