modeling_conventions

Pathfinder Solutions

web: www.pathfindersol.com

90 Oak Point Wrentham, Massachusetts 02093 U.S.A

voice: +01 508-384-1392

fax: +01 508-384-7906

MBSE

Modeling Conventions

2/8/00

Peter J. Fontana

version 1.6

MBSE Modeling Conventions

1. INT R ODUCT ION

This document provides a summary of common rules and conventions applied to Analysis
modeling of MBSE systems. These rules and conventions have been developed to ensure the
Analysis models are:

populated with valid, consistent and understandable Analysis abstractions

free of analyst-level errors caused by bad programming practice

valuable to both the maintenance developer and the external expert reviewer

Please note that these conventions assume a base of syntactically correct models that pass all
checks provided in Pathfinder’s Springboard translation engine.

It is assumed that the reader is familiar with the MBSE approach as introduced in:

" Model-Based Software Engineering - An Overview of Rigorous and Effective Software
Development using UML



”

", Pathfinder Solutions, 1998; (this paper is available from

www.pathfindersol.com)

2. General Conventions

2.1 Naming And Descriptions

While the UML notation provides some semantic meaning through the graphic icons employed,
the true meaning of Analysis models comes from the Analysis element names and descriptions.
These textual elements must be carefully crafted to convey the necessary concepts. The
general audience for names and descriptions are assumed to be:

familiar with UML in general and with MBSE in particular

generally knowledgeable in the domain’s subject matter

Analysis element names and descriptions are:

Clear, concise, and unambiguous

Appropriate to the subject matter of their domain

In addition, names and descriptions should take care to avoid restating points apparent from the
analysis itself. EG: avoid an attribute description that starts with “This is the attribute
of the Foo class which…

”

2.2 Capitalization

These conventions help the reader – especially at the Action Language level – understand what
some Analysis elements are simply from how their names are capitalized and underscored. (The
rules are in regular expression syntax).

DomainName, DomainServiceName, ClassName, StateName, EventName: [A-Z][A-
Z,a-z,0-9]*

attributeName, objectServiceName: [a-z][A-Z,a-z,0-9]*

data_type_name_t (for non-enum project-specific data types): [a-z][a-z,0-9_]*_t

enum_name_e (for project-specific enumerates): [a-z][a-z,0-9_]*_e

action_local_variable, service_parameter, event_parameter: [a-z][a-z,0-9_]*

MBSE Modeling Conventions

2.3 Diagrams

Software modeling affords the benefits of a two-dimensional form of expression – diagrams. A
diagram can convey a lot of information in a small space – provided the needs of the reader are
kept in mind.

Origination legends (Popkin “doc blocks”) are placed in the upper left corner of every
diagram, and include the author’s name, and a document version number. This number
is <build number>.<sequence number>. The build number indicates the build the
current diagram work is intended for, and sequence number indicates the revision level
within that build. (Please note that a diagram last edited in build 1 will retain its 1.xx
version number throughout the project, until it is edited again. Versions are changed
only when actual changes are made.)

The graphical layout groups related diagram elements together, and maintains uniform
alignment and spacing to reinforce this grouping.

Care is taken in layout of connecting lines to avoid line crossover where possible.

Connecting lines are routed with a minimum of intermediate nodes

MBSE Modeling Conventions

3. Domain Model

Name domains to be reusable and independent of vendor: EG: choose “GUIToolkit”, not
“MSVisualEnvironment”.

Bridge lines are straight, and at any angle

4. Information Model

Class names are singular – use a 1:1..* (or 1..*:1..*) association to show plurality instead

Each class prefix is unique both within the domain and does not overlap with domain
prefixes.

Attributes are named from the perspective of their classes. This can afford some
economy in the name, EG: for the Hospital class use mainPhoneNumber instead of
hospitalMainPhoneNumber

Association names are A<number>

Association role phrases use the same naming as local variable names: [a-z][a-
z,0-9_]*

Inheritance relationships are named: S<number>

Do not use disjoint inheritance hierarchies ,, EG:

Dog

BigDog

SmallDog

RedDog

BlackDog

Instead use a discriminant attribute (where appropriate):

Dog
(D)

color

BigDog

SmallDog

Association and inheritance lines are straight and orthogonal.

Association names are located near the center of association lines

Association role phrases are located near their respective ends of their of association
lines

The supertype ends of inheritance lines are aligned to present a single arrowhead.

Do not use multiple inheritance.

MBSE Modeling Conventions

5. Scenario Model

5.1 System Level

Only show domains on system-level scenario models, and only show domain service
invocations between the domains

5.2 Domain Level

Show the “local” domain as the first object lifeline on the left

Show server domains as the last object lifelines on the right

In general, show external impetus as coming from “offpage” (the left margin) to avoid
specifying a client. (If your editor requires a lifeline at both ends of all interactions, then
specify a domain named “<client>”)

Show only the following interactions:

Create

Delete

CALL <service handle name>

6. State Model

State names convey the lifecycle stage of a class instance for some finite span of time.
Their names need to reinforce this, and present perfect tense can help. EG: use
RaisingRamp

instead of RaiseRamp

Event names identify a single instance in time, and past tense can help. Their names
need to reinforce this. EG: use DoorClosed instead of DoorClose.

Transition lines are straight and orthogonal.

Event labels are located near the source end of their transition lines.

Avoid deferred events if possible. It can make the dynamics of the model difficult to
follow.

7. Action Model

In Action Modeling it is important to follow some of the more general rules of structured
programming:

Only services returning a specific value need an exit point

When necessary, use a single exit point (RETURN statement)

Reduce individual action scope to fit within 100 lines

Have a single statement on a line

Indent statement frames within control structures

Provide liberal commenting, including:

•

summary at the top of the action, or in the state action summary

•

descriptions for each statement frame of a control structure (IF/ELSE, FOREACH,
WHILE)

MBSE Modeling Conventions

•

something for any line that is not patently self explanatory

Take care when defining and using polymorphic events or services. The lowest level
class in the hierarchy that can act on it will.

Proper action modeling is necessary to enforce the rules and policies of the domain.
Unconditional associations need to be enforced by the actions:

When creating an instance of a class that has an unconditional relationship, the
associated class instance should either be pre-existing or created shortly afterward, in
the same unit of action language if possible.

Link unconditional associations as soon as possible after creating the participants (but in
all cases complete the link within the execution of the creating state action, or within the
services it calls)

Even unconditional associations, however, do not guarantee successful navigation. An explicit
LINK must have been completed before navigation:

In all navigations, either provide defensive logic to handle “not found” cases, or
explicitly comment where (action name) the link is guaranteed to have happened

Separating the retrieval of an instance reference from it subsequent use can aid Design-level
error catching, help with readability, and aid debugability:

when invoking a service or method that returns an instance reference, catch this
reference in a variable before using it. eg: Instead of using this:

MO:PickBiggest().selected = TRUE;

do this:

Ref<MyObject> mo;

mo = MO:PickBiggest();

mo.selected = TRUE;