Pathfinder Solutions
N
S
W
E
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
copyright entire contents 1995 - 2000
Pathfinder Solutions all rights reserved
MBSE Modeling Conventions
1
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
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
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
S2
S2
S1
S1
Instead use a discriminant attribute (where appropriate):
Dog
(D)
color
BigDog
SmallDog
S1
S1
-
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
4
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:
o
<domain prefix>:<domain service name>
o
<object prefix>:<object service name>
o
<object prefix>:<event name>
o
Create
o
Delete
o
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
5
•
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;