UML guidelines
•
3 likes•1,892 views
The document provides guidelines for using UML diagrams to model software systems. It recommends focusing on key diagrams like class and sequence diagrams. Packages are recommended to divide large models into manageable pieces, with dependencies shown between packages. Textual descriptions should complement the diagrams. Over-modeling is discouraged in favor of clear, essential diagrams.
Recommended
More Related Content
Similar to UML guidelines
Similar to UML guidelines (20)
Recently uploaded
Recently uploaded (20)
UML guidelines
- 3. REC. 2 USE NATURAL LANGUAGE TO COMPLEMENT UML MODELS...............................................4 REC. 3 AVOID OVERMODELING....................................................................................................................5 REC. 4 USE THE PACKAGE DIAGRAM TO DIVIDE THE DIAGRAM INTO MORE MANAGEABLE PIECES..........................................................................................................................................................6 REC. 5 USE THE PACKAGE DIAGRAM TO REPRESENT THE HIGH LEVEL VIEW OF THE SYSTEM.........7 REC. 6 ATTACH UML STEREOTYPES TO PACKAGES TO DESCRIBE THE TYPE OF PACKAGE......9 REC. 7 DEFINE ONLY THE MOST ESSENTIAL USE CASES......................................................................10 REC. 8 USE A STANDARD FORMAT TO DESCRIBE USE CASES TEXTUALLY....................................10 REC. 9 AVOID TOO MUCH DETAIL IN CLASS DIAGRAMS....................................................................11 REC. 10 AVOID COMPLEX ASSOCIATIONS BETWEEN CLASSES..........................................................11 REC. 11 NAME AN ASSOCIATION ONLY IF IMPROVES UNDERSTANDING....................................11 REC. 12 ATTACH UML STEREOTYPES TO CLASSES TO DESCRIBE THE TYPE OF CLASS..............11 REC. 13 DESCRIBE ONLY THE MOST IMPORTANT SEQUENCES..........................................................13 REC. 14 DESCRIBE EXTERNAL OBJECTS WITH AN ACTOR SYMBOL IN SEQUENCE DIAGRAMS.13 REC. 15 USAGE OF ARROW SYMBOLS IN SEQUENCE DIAGRAMS......................................................13 REC. 16 USE THE STATECHART DIAGRAM ONLY IN SPECIAL CASES..............................................14 REC. 17 USE THE RECOMMENDED COMPONENTS IN DEPLOYMENT DIAGRAM.........................22
- 4. 2 GENERAL These guidelines are based on an approach that unnecessary activities are harmful. With real software projects, there is no time to play around with useless diagrams or theories. Therefore, only the most essential techniques in deploying UML are recommended in this document. You don't have to be on a highceremony project to find using bits of the UML handy. You don't have to use all of it, just the bits you find useful. Rec. 1 Not all the diagrams in UML are useful. The most important diagrams in UML are: • class diagram • sequence diagram The following diagrams in UML are needed sometimes: • use case diagram, • statechart diagram • component diagram Use the following diagrams only in special cases: • deployment diagram • collaboration diagram • activity diagram Rec. 2 Use natural language to complement UML models. Natural language is an essential modeling tool. Natural language is the way to capture requirements; it is typically used whenever there is a need to communicate with end users. Natural language is also used if there is a need to emphasize something related to diagrams. The UML diagram is usually not enough to describe the system. Textual descriptions of diagrams are also needed in the documents. You can also use the UML note in diagrams to give more information.
- 5. U se- ase M odeloft O r C he der S yst em T he use-case m odelspecii t fes he behavi and suroundi or r ngs oft syst he em i t m s ofuse cases and act s.T he n er or descrpton ofan act oruse case i i i or s found i is specii i w hi i n t fcaton, ch s di ayed w hen doubl cl ng on t spl e- icki he act oruse case.T he docum ent i or aton fel on t G ener t i d he al ab,i di ayed i s spl n t appl i w i he i on ndow w hen you sel cat ect M anage O rder and act oruse case.(fnot cl or I , i ck D ocum ent i on t V i m enu. aton he ew ) Or derA dm i stat ni r or M anage C ust erR egi er om st I ead ofdescrbi t fow ofevent nst i ng he l s ofa use case i t docum ent i fel n he aton i d ofis specii i an ext naldocum ent t fcaton, er w ih t descrpton can be connect t t he i i ed o t use case,w hi i done on t he ch s he D i am t i is specii i agr ab n t fcaton. M anage A ri es tcl T he use cases constt e t f iut he unctonal i requiem ent on t syst .T hey al r s he em so S t e Adm i stat or ni r or defne how t r i he equiem ent ar r s e di rbut am ong t desi obj s of sti ed he gn ect E xecut O r e der t syst ,i, how t obj s i er he em .e. he ect nt act t peror each use case.I t B r ser o f m n he ow you can see t hatt M anage O r he deruse case i descrbed i t o i er i s i n w nt acton di am s oft t agr he ype sequence di am . agr Figure 1. Use natural language to complement UML models. Rec. 3 Avoid overmodeling. Choose undermodeling instead of overmodeling. Draw the diagrams at the proper level of abstraction and illustrate only what is essential. Make sure that the diagrams are clear and readable. Add textual commentary instead of overmodeling.
- 6. 3 PACKAGE DIAGRAM One of the oldest questions in software methods is: How do you beak down a large system into smaller systems? We ask this question because as systems get large, it becomes difficult to understand them and the changes we make to them. One idea is to group the classes together into higherlevel units. This idea, applied very loosely, appears in many objectoriented methods. In the UML, this grouping mechanism is called the package. The idea of packages can be applied to any model element, not just classes. Without some heuristics to group classes together, the grouping becomes arbitrary. The one I have found most useful and the one stressed most in the UML is the dependency. Rec. 4 Use the package diagram to divide the diagram into more manageable pieces. Packages are a vital tool for large projects. If your diagram doesn’t fit in a page or if there are more than 20 elements in your diagram, your diagram is obviously too big. AddNE UpdateNE InitializeNavigator ManageNavigator ManageNE DeleteNE ManageTopology ManageTrunk AddTrunk Operator UpdateTrunk UpdateNetworkObjectState DeleteTrunk ManageSystem MoveNetworkObject Bind Unbind ManageServer ManageDomain AddServer UpdateServer DeleteServer Figure 2. Bad example: all use cases in the same level
- 7. Operator Initialize Navigator Manage Navigator Manage System Manage Topology (from Navigator Management) (from System Management) (from Topology Management) Figure 3. Good example: use cases divided into packages. Rec. 5 Use the package diagram to represent the high level view of the system. In the high level view, each package represents a subsystem. Arrows between packages illustrate dependencies between parts of the system. A dependency exists between two elements if changes to the definition of one element may cause changes to the other subsystem that provides services to another subsystem is a server and it is symbolized with the arrow end in the relationship. A subsystem depends on another subsystem if the functionality of the first subsystem cannot be fully used without the other. 3rd Party Application SMS System M M NMS System 3rd Party System Figure 4. Associations between systems.
- 8. <<layer>> Service Platform Browser M M <<subsystem>> <<subsystem>> Service Customer M Management Management M M <<subsystem>> Cross-Domain Management M M M Kernel M M Database Figure 5. Associations between functional subsystems. Applications Core Platform Kernel Database Figure 6. Associations between layers.
- 9. <<s ublayer>> Service Platform Browser (from Application) <<s ublayer>> Client Applicat ions (from Application) <<s ublayer>> Platform (from Application) Figure 7. Associations between sublayers. Rec. 6 Attach UML stereotypes to packages to describe the type of package. The following stereotypes are recommended: • <<system>> • <<subsystem>>
- 10. 4 USE CASE DIAGRAM Use cases should give a general overview what a user can do with this system. The use case diagram is an implementationindependent look at the system. It focuses on a highlevel picture of what the system will do, without worrying about the details of how the system will do it. Good use cases can be used when planning system tests or writing user manuals. Requirements concerning the functionality of the system should be mapped to use cases. Rec. 7 Define only the most essential use cases. It is not necessary to define all the possible use cases. Analyze only the most important functional requirements of the system as use cases. You can group use cases according to their importance. Rec. 8 Use a standard format to describe use cases textually. It is not necessary to express use cases graphically with use case diagram. Use cases can also be expressed textually. Use the following format with use cases: Use Case Name: Description: Preconditions: Work flow in steps: Postconditions: Exceptions: Actors: Timing Constraints:
- 11. 5 CLASS DIAGRAM Rec. 9 Avoid too much detail in class diagrams. Represent only the most important attributes and methods e.g. only the public attributes and methods. Avoid describing attribute types, method types and method parameters in class diagrams. This way it will be easier to keep the class diagrams uptodate later. Rec. 10 Avoid complex associations between classes. UML supports many different types of associations. Complex associations typically cause misunderstanding among developers. Describe the associations in textual form in UML note or in the specification document. However, all the associations should be modeled because the dependencies between classes represent important information. The following associations are recommended: • Unidirectional association. Navigability exists in only one direction. Use the bidirectional association (navigability in both directions) in special cases as unidirectional is sufficient in most cases. • Multiplicity. Indicates how many objects may participate in the given relationship. The most common multiplicities in practice are • 1 (exactly one) • * (the range 0..infinity) • 0..1 (either none or one) • Generalization. Generalizations are associations between more general elements and more specific elements in which the more specific elements are fully consistent with the more general elements and inherit and may add information to the characteristics provided by the more general elements. • Aggregation. The partof relationship. Example: a car has an engine and wheels as its parts. • Dependency. Dependencies are associations between a collection of dependent client elements and another collection of independent supplier elements. The client elements require knowledge of and the presence of the supplier elements. Dependencies are used to model dependencies among model elements where changes in the independent supplier elements may require changes to the dependent client elements. Example of a dependency: a parameter reference or the creation of an object. Rec. 11 Name an association only if improves understanding. It is not necessary to name every association. Association names like “has” or “is related to” are often useless. Rec. 12 Attach UML stereotypes to classes to describe the type of class. The following stereotypes are recommended: • <<interface>> • <<abstract>>
- 12. NMSNetworkElement NMSEquipment NMSInterface NMSTrunk id unit interface id name type ATMaddress fromInterface coordinates state IPaddress toInterface type IPsubnetworkAddress type type capacity capacity state state availability <<Interface>> <<Interface>> <<Interface>> <<Interface>> NMSNetworkElementHandler NMSTrunkHandler NMSEquipmentHandler NMSInterfaceHandler get() getByNetworkElement() getByNetworkElement() getByNetworkElement() getAllByTime() getByCircuit() statistics() NMSEquipmentFault NMSCustomerSite id customerId faultSource siteId affectedCircuits name problemDescription address specifier modem spt networkElementInterface gpt IPsubnetworkAddresses maintenanceStatus type severity description acknowldgeTime coordinates onTime contact offTime telephoneNumber faxNumber <<Interface>> <<Interface>> NMSEquipmentFaultHandler NMSCustomerSiteHandler getAllByTime() create() getByNetworkElement() modify() getByCircuit() getByCustomer() getAll() Figure 8. Good example of a class diagram.
- 13. 6 SEQUENCE DIAGRAM The rationale for using sequence diagrams is to illustrate how use cases are implemented in the system. Sequence diagram can describe interaction between systems, subsystems, modules or classes. Rec. 13 Describe only the most important sequences. There is no need to describe all the possible sequences in the system. This kind of approach helps to keep models uptodate later. Rec. 14 Describe external objects with an actor symbol in sequence diagrams. It should be possible to distinguish internal objects from the external objects. Rec. 15 Usage of arrow symbols in sequence diagrams. Use only the basic symbols. Add textual commentary in more complicated cases. Use only the following symbols in sequence diagrams: • Simple. For messages with a single thread of control, one object sends a message to a passive object. • Asynchronous Asynchronous communication occurs, when the client sends a message to the supplier for processing, and continues to execute its code without waiting for or replying on the supplier’s receipt of the message.
- 14. 7 STATECHART DIAGRAM A statechart diagram shows the states of a single object, the events or messages that cause the transition from one state to another and the actions that result from a state change. Rec. 16 Use the statechart diagram only in special cases. Use the statechart diagram if you want to describe a complicated algorithm. Use the statechart for objects with complex, dynamic behavior to exemplify the states of an object during its lifetime. Statechart diagrams can also be used to visualize the dialog structure of the GUI. Here, a state stands for a dialog box, window, or Web page. An event causes a movement from one dialog to another.
- 15. 8 COMPONENT DIAGRAM One of the main problems in UML at the moment is how to use components. Common modeling techniques with components are introduced in this subchapter. Components are clarified in the appendix. 8.1 Standard UML stereotypes for components All the UML's extensibility mechanisms apply to components. The UML defines five standard stereotypes that apply to components. 1. <<executable>> Specifies a component that may be executed on a node. 2. <<library>> Speficies a static or dynamic object library. 3. <<table>> Specifies a component that represents a database table. 4. <<file>> Specifies a component that represents a document containing source code or data. 5. <<document>> Specifies a component that represents a document.
- 16. 8.2 Organizing components You can organize components by grouping them in packages organize in the same manner in which you would organize classes. kernel genos servletFW util configuration core log validator xml framework workhorse Figure 9. Platform components (Java classes) organized into packages.
- 17. 8.3 Modeling executables and libraries To model executables and libraries: • Model the deployment components that make up your implementation. • Identify the partitioning of your physical system. • Model any deployment components: executables and libraries. • Model the relationships among these components. • It is important to model the dependencies of these elements in order to visualize the impact of change. • For larger systems that are deployed across several computers, it is useful to model the way the components are distributed by asserting the nodes on which they are located. • Stereotypes used • <<executable>> • <<library>> • <<interface>> • Rose specific: <<EXE>> • Rose specific: <<DLL>> <<EXE>> Deployment something.exe components of the physical system and their dependencies. <<DLL>> <<DLL>> <<DLL>> libx.dll liby.dll libz.dll Figure 10. Executables, libraries and their relationships.
- 18. 8.4 Modeling tables, files and documents To model tables, files, and documents: • Deployment components that are neither executables nor libraries and yet are critical to the physical environment, e.g. data files, help documents, scripts, log files, initialization files, and installation/removal files. • Identify the ancillary components that are part of the physical implementation of your system and model these things as components. • You can also include other executables, libraries and interfaces in the same diagram. Model the dependencies among these parts. • Stereotypes used • <<executable>> • <<library>> • <<interface>> • <<table>> • <<file>> • <<document>> <<EXE>> myhelp.hlp something.exe start.ini <<DLL>> <<DLL>> <<DLL>> libx.dll liby.dll libz.dll Deployment components of the physical system and their dependencies. Other deploytment components also included. Figure 3. Executables, libraries and other deployment components. 8.5 Modeling an API To model an API: • Model the component and its interface. • Expose only those properties of the interface that are important to visualize in the given context.
- 19. • You can also include the signatures for each operation in the API. • Stereotypes used • <<executable>> • <<interface>> AVCLi CreateLi DeleteLi GOSLi Listener Notif ia stener stener stener stener Adapter ble AVCListener DeleteListen GOSListener ListenerAda Notif iable CreateListen pter er er Figure 4. Components (Java classes) and their interfaces. 8.6 Modeling source code To model source code: • Model the configuration of all the source code files that your development tools use to create these components. • These represent the work product components of your development process. • This is useful for visualizing the compilation dependencies among the source code files. DateFor LogMs matter g Log CallerI nfo Comma ErrorL TraceL StackTra ndLog og og ceParser LogBa se Figure 5. Source file components in Log.
- 20. RMIBri RMICoreCo RMIGenO dge_i mponent SClient DataO GOSFi GOSId GOSS Operativ eP bject lter elect arameter RMIBridge_i RMICoreCo mponent Attribu te Operativ ePa rameter Figure 6. Some of the source file components in GenOS.
- 21. 9 DEPLOYMENT DIAGRAM Deployment diagrams show the configuration of runtime processing elements and the software components, processes, and objects that live on them. Software component instances represent runtime manifestations of code units. Components that do not exist as runtime entities (because they have been compiled away) do not appear on these diagrams, they should be shown on component diagrams. <<computer>> Web Client WS <<module>> Web Browser <<applet>> Client Applet <<HTML page>> GUI <<computer>> Web Server <<module>> <<module>> HTTP Server Servlet Engine <<servlet>> Client Servlet <<module>> XSLT Processor <<computer>> Management Server <<computer>> Database Server Example 11. Deployment view: SMS system structure.
- 22. Rec. 17 Use the recommended components in deployment diagram. Components presented in deployment diagram are: • EXE • process • file • class (only in Java) • jar (only in Java)
- 23. 10 UML DIAGRAMS IN SPECIFICATION DOCUMENTS 10.1 General There are three perspectives you can use in drawing diagrams (especially class diagrams): • Conceptual. This perspective is used in functional specification. If you take the conceptual perspective, you draw a diagram that represents the concepts in the domain under study. These concepts will naturally relate to the classes that implement them, but there is often no direct mapping. Indeed, a conceptual model should be drawn with little or no regard for the software that might implement it, so it can be considered language independent. Class diagrams can be extremely valuable here, as long as you draw them from the conceptual perspective. In other words, you should treat each class as a concept in a user's mind. The class diagrams you draw are then not diagrams of data or of classes, but rather of the language of your users. • Specification. This perspective is used in system/subsystem architecture specification. Now we are looking at software, but we are looking at the interfaces of the software, not the implementation. Objectoriented development puts a great emphasis on the difference between interface and implementation, but this is often overlooked in practice because the notion of class in an OO language combines both interface and implementation. This is a shame, because the key to effective OO programming is to program to a class’s interface rather than to its implementation • Implementation. This perspective is used in module specification. In this view, we really do have classes and we are laying the implementation bare. This is probably the perspective used most often, but in many ways the specification perspective is often a better one to take. It is very important to separate the specification perspective and the implementation perspective. Perspective is not part of the formal UML, but it has been found extremely valuable when modeling and when reviewing models. The UML can be used with all three perspectives. By tagging classes with a stereotype, you can provide an indication of the perspective. You mark classes with <<implementation class>> to show the implementation perspective, and with <<type>> for the specification and conceptual perspective. 10.2 Functional specification The UML models in functional specification should at least answer the following questions: 1. What is the problem? 2. What kind of solution solves the problem? The following diagrams are recommended: • analysis class diagram • use case diagram The following diagrams are optional: • statechart diagram
- 24. 10.3 System architecture/subsystem architecture specification The UML models in system architecture specification should answer at least the following questions: 1. What is the logical partitioning of the system into subsystems? Knowing this helps you to understand the overall structure of the system and to comprehend how system functionality is allocated. 2. What is the runtime configuration of the system? Designing what processes there are, how they relate, and how they are allocated to available computers is an essential part of architectural design. This helps in debugging the system and estimating its performance as well as in planning the development and the integration order. 3. What is the configuration of the developed system in terms of components? This helps in organizing the development and integration work as well as in software configuration management. 4. How does the architecture implement the most important use cases? This provides visibility to design rationale and makes it possible to validate the performance of designed system from the user’s point of view. The following diagrams are recommended: • package diagram • deployment diagram • component diagram • sequence diagram 10.4 Module specification The following diagrams are recommended: • class diagram • sequence diagram The following diagrams are optional: • statechart diagram
- 25. 11 APPENDIX 11.1 Components Components live in the material world of bits and therefore are an important building block in modeling the physical aspect of a system. A component is a physical and replaceable part of a system that conforms to and provides the realization of a set of interfaces. 11.1.1 Logical and physical views You do logical modeling to visualize, specify, and document your decisions about the vocabulary of your domain and the structural and behavioral way those things collaborate. You do physical modeling to construct the executable system. Whereas these logical things live in the conceptual world, the physical things live in the world of bits that is, they ultimately reside on physical nodes and can be executed directly or can, in some indirect manner, participate in an executing system. In the UML, all these physical things are modeled as components. A component is a physical thing that conforms to and realizes a set of interfaces. Interfaces therefore bridge your logical and physical models. For example, you may specify an interface for a class in a logical model, and that same interface will carry over to some physical component that realizes it. 11.1.2 Components vs. classes There are some significant differences between components and classes. • Classes represent logical abstractions; components represent physical things that live in the world of bits. In short, components may live on node, classes may not. • Components represent the physical packaging of otherwise logical components and are at a different level of abstraction. Components represent the physical packaging of a set of other logical elements, such as classes. • Classes may have attributes and operations directly. In general, components only have operations that are reachable only through their interfaces. 11.1.3 Binary replacealibity The basic intent of every componentbased operating system facility is to permit the assembly of systems from binary replaceable parts. • A component is physical. It lives in the world of bits, not concepts. • A component is replaceable. A component is substitutable it is possible to replace a component with another that conforms to the same interfaces. • A component is part of a system. A component rarely stands alone. Rather, a given component collaborates with other components and in so doing exists in the architectural or technology context in which it is intended to be used. • A component conforms to and provides the realization of a set of interfaces. 11.1.4 Types of components Three kinds of components may be distinguished.
- 26. 1. Deployment components. Components necessary to form an executable system. Examples: DLL, EXE. Also CORBA and EJB components are deployment components. 2. Work product components. These components are essentially the residue of the development process, like things from which deployment components are created. These components do not directly participate in an executable system but are the work products of development that are used to create the executable system. Examples: source code files, data files. 3. Execution components. These components are created as a consequence of an executing system. 11.2 FAQ Frequently asked questions: QUESTION: What is the purpose of modeling? ANSWER: Developing a model for an industrialstrength software system prior to its construction or renovation is as essential as having a blueprint for large building. Good models are essential for communication among project teams and to assure architectural soundness. As the complexity of systems increase, so does the importance of good modeling techniques. There are many additional factors of a project’s success, but having a rigorous modeling language standard is one essential factor QUESTION: What is modeling? ANSWER: Modeling is the easiest way of moving you step by step through the processes of: Identifying the requirements of the application and modeling business processes Mapping requirements to abstract business objects, identifying and applying design patterns, and creating usage scenarios Identifying and designing business objects or partitioning services across a three tiered services model Mapping business objects to software components and designing how components will be distributed across a network QUESTION: What problems does visual modeling address? ANSWER: The problems that visual modeling addresses are: • Software that poorly fits user needs • Inability to deal with changing requirements • Software integration problems • Discovery of serious flaws too late in the project • Software that is hard to maintain and extend QUESTION:
- 27. When do I need modeling? ANSWER: Modeling can be useful at any point in the application development process. When first building an application, your time is much better spent dealing with issues such as the planned business uses and how you will implement a programming environment to address these business issuesnot where and how you are going to place the buttons on your first screen. Modeling can also be introduced in the middle of an existing project. Rational Rose includes powerful tools for reverse engineering as well as forward engineering of classes and component architectures. You can gain valuable insights to your asbuilt architecture and help pinpoint deviations from the original design. QUESTION: What is the UML? ANSWER: The Unified Modeling Language (UML) is considered the de facto standard object modeling language in the industry. The UML is the evolution of early approaches to objectoriented analysis and design. Based on the seminal works by Grady Booch, Ivar Jacobson, and Jim Rumbaugh in the Booch, OOSE, and Object Modeling Technique (OMT) methods, these three Rational experts have provided the basis for the next generation of visual software modeling. The UML details the application modeling language for: • Business process modeling with use cases • Class and object modeling • Component modeling • Distribution and deployment modeling QUESTION: What is UML? ANSWER: The Unified Modeling Language (UML) is the industrystandard language for specifying, visualizing, constructing, and documenting the artifacts of software systems. Using UML, programmers and application architects can make a blueprint of a project, which, in turn, makes the actual software development process easier. QUESTION: Who created UML? ANSWER: UML was created at Rational Software by methodologists Grady Booch, Ivar Jacobson, and Jim Rumbaugh with input from other leading methodologists, many software vendors, as well as endusers. Its aim is to unify the various existing systems into a bestofbreed modeling language. QUESTION: Is UML a standard?