MDA Modeling Conventions

Transcription

1 Peter J. Fontana Version 2.0 May 25, 2004 PathMATE Series Pathfinder Solutions LLC 90 Oak Point Wrentham, MA USA by Pathfinder Solutions

2 Table of Contents PathMATE Overview...iii 1. Introduction General Conventions... 1 Naming and Descriptions... 1 Capitalization... 2 Diagrams Diagram-Specific Conventions... 3 Domain Model... 3 Class Diagram... 3 Scenario Model... 4 State Model... 5 Action Model... 5 Analysis Level User-Defined Types... 6 ii

3 PathMATE Overview This overview introduces Model Driven Architecture (MDA) and the PathMATE tools that make MDA work. MDA and PathMATE move you from writing and debugging code to developing and testing the logic of a high performance system. Over years of rigorous refinement in several industries, PathMATE tools have proven their value in rapid and effective software systems development. PathMATE Toolset The PathMATE Model Automation and Transformation Environment includes all the tools required to transform your MDA models into highperformance systems (Figure 1). Figure 1. PathMATE Toolset iii

4 The three parts of the PathMATE toolset cooperate to turn your models into executable systems: Transformation Maps Generate C, C++, or Java software with off-the-shelf Transformation Maps, or create custom maps to drive output for other languages or specific platforms. Transformation Engine The Engine transforms platformindependent models into working, embedded software applications. Spotlight Verify and debug your application logic with Spotlight, the most advanced model testing environment available. No other MDA transformation environment offers a more open or configurable set of development tools, designed to meet the requirements of systems engineers. How PathMATE Works Use Model Driven Architecture to build complex embedded systems that meet rigorous standards for speed and reliability. MDA works because it separates what the system does from its deployment on a particular platform. PathMATE adds these advantages: Greatest architectural control A highly configurable Transformation Engine enables you to optimize output for resource-constrained platforms. Clean separation of model and code Conforming to the MDA paradigm, PathMATE models contain no implementation code. That gives you fast and flexible deployment and migration capabilities. Configurable, target-based model execution and testing Preemptively eliminate platform-specific bugs, minimize quality assurance resources, and accelerate development. Lowest cost of ownership Integrate PathMATE with your existing UML editor. Build on your previous investment in training and software. Speed Even large transformations take just seconds with PathMATE. That enables highly iterative model development, and rapid transformation and test cycles. Try the demonstration software available at to get started quickly and easily. iv

5 1. Introduction This document provides a summary of common rules and conventions applied to Analysis modeling of embedded 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 the PathMATE Transformation Engine. It is assumed that the reader is familiar with the MDA approach as introduced in Model Based Software Engineering: Rigorous Software Development with Domain Modeling, Pathfinder Solutions, (This paper is available from 2. General Conventions 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. For example, avoid an attribute description that starts with This is the attribute of the Foo class which 1

6 Capitalization Diagrams 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 SYMBOLIC_CONSTANT, ENUMERATE_LABEL: [A-Z][A-Z,0-9,_]* action_local_variable, service_parameter, event_parameter: [az][a-z,0-9_]* 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. NOTE: 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. 2

7 3. Diagram-Specific Conventions Domain Model Name domains to be reusable and independent of vendor. For example, choose GUIToolkit, not MSVisualEnvironment. Bridge lines are straight, and at any angle. Class Diagram 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. For example: Dog S1 S1 S2 S2 BigDog SmallDog RedDog BlackDog Instead use a discriminant attribute (where appropriate): Dog (D) color S1 S1 BigDog SmallDog 3

8 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. Scenario Model System Level Only show domains on system-level scenario models, and only show domain service invocations between the domains. 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 types of interactions (the exact syntax is dependent on your choice of UML editor): <domain prefix>:<domain service name> <object prefix>:<object service name> <object prefix>:<event name> Create Delete CALL <service handle name> 4

9 State Model Action 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. For example, use RaisingRamp instead of RaiseRamp. Event names identify a single instance in time, and past tense can help. Their names need to reinforce this. For example, 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. 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) 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 preexisting 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). 5

10 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 its 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. For example, instead of using this: do this: MO:PickBiggest().selected = TRUE; Ref<MyObject> mo; mo = MO:PickBiggest(); mo.selected = TRUE; Analysis Level User-Defined Types In an effort to help the analyst understand where various types are defined and to afford a form of name-space scooping at the implementation level, the following naming conventions are applied to user defined types. Scope Identification System-level data types are prefixed with sys_ System-level symbolic constants and enumerate labels are prefixed with SYS_ Domain-level data types are prefixed with <domain prefix>_ (in lowercase) Domain-level symbolic constants and enumerate labels are prefixed with <DOMAIN PREFIX>_ (in uppercase) Enumerate Label Grouping with Enumerate Type Even with defining scope prefixes on enumerate labels, it can be very difficult to identify which enumerate type definition and enumerate label is defined within without help. This convention helps in a type scope with many enumerate types: Enumerate label names are built from the scope prefix, and an identifying segment from the enumerate type name, followed by an identifying element from this value. Example: ENUM sys_traffic_light_color_e { SYS_TRAFFIC_LIGHT_RED, SYS_TRAFFIC_LIGHT_GREEN, SYS_TRAFFIC_LIGHT_BLUE}. (Sorry we re out of yellow.) 6