Guidelines for UML Diagram Development

This document contains guidelines and hints (and lists common mistakes) for the development of UML diagrams.

1. Domain Modeling Hints and Mistakes
   
2. Use Case Diagram Hints and Mistakes
   
3. Robustness Analysis Hints and Mistakes
   

Domain Modeling Hints and Mistakes

The following list of "common domain modeling mistakes" is based on observed behavior of students in a study conducted by Rosenberg and Scott. Here's their list of what to avoid:

1. Don't get carried away with an exhaustive "noun and verb" analysis. Rather, simply use this technique to get your object discovery started.

2. Don't assign operations to classes without also exploring use cases and sequence diagrams.

3. Don't optimize the system for reusability before making sure all of the user's requirements have been satisfied.

4. Don't get hung-up over issues of "aggregation" or "composition" in the part-of associations.

5. Don't presume a specific implementation strategy (e.g., use of technology) without making the problem space.

   Implementation issues should be left until the physical design stage.

6. Don't use hard-to-understand names for the classes.

   Easy-to-understand names enhance communication among members of a development team. Acronyms should be avoided until the implementation stage.

7. Don't create a one-for-one mapping between domain classes and relational database tables.

   If you are reengineering a legacy system that uses a relational database, then the tables within the database are likely to be an excellent source of domain classes. However, be careful not to bring them over to your static model wholesale. Relational tables can have lots of attributes that might not belong together in the context of an object model. You should use "aggregation" to factor groups of attributes in so-called "helper" classes, which contain attributes and operations relevant to more significant classes.

8. Don't make premature use of "patterns" that look cool but have little or no connection to user problems.

   Often, patterns only become apparent during robustness analysis where their connectivity to use cases become apparent. Design patterns can, however, be highly useful in the context of sequence diagrams and design-level class diagrams.

Use Case Diagram Hints and Mistakes

The following list of "common use case mistakes" is based on observed behavior of students in a study conducted by Rosenberg and Scott. Here are their mistakes to avoid:

1. Don't write functional requirements instead of usage scenario text.

   Requirements are not the same as scenarios. Requirements are generally stated in terms of what the system shall do. Usage scenarios, in contrast, describe the actions users take and the responses the system will generate (i.e. behavior).

   Eventually, use case text/graphics will be used as a run-time behavioral specification for the scenarios that are described. (i.e. on the left-hand side of the sequence diagram). We want to be able to see how the system (shown with objects and messages in the sequence diagram) impliments the desired behavior as required in the use case test.

2. Don't describe attributes and methods instead of usage.

   Use cases should describe system usage, using terms from the problem domain. The should not contain too many details about methods or attributes of the domain classes/objects.

3. Don't write use cases too tersely.

   Textual descriptions of use cases should contain all of the details of user actions and system responses. It's better to err on the side of providing too much detail, then leave something out.

4. Don't divorce yourself from the user interface (system-user interfaces).

   One of the fundamental notions of "use-case driven" development is that the development team conforms to the design of the system from a user's perspective. You cannot do this without being specific about what actions a user will take. This includes discussing those features of the user interface that allow a user to tell the system to do something.

5. Don't avoid explict names for the boundary objects.

   Boundary objects are the objects with which actors will interact. In the case of a software system, boundary objects can be graphical components such as pulldown menus, buttons, and so forth.

   In keeping with the theme of providing ample detail and being explicit about user navigation, we submit that a use case should name boundary objects explicitly.

6. Don't write in the passive voice, using a perspective other that the system user's.

   A use case is most effectively written from a user's perspective as a set of present-tense verb phases in active voice.

7. Don't describe only user interactions; ignore system responses.

   The narrative of a use case should be event-response oriented. For example,

   "The system does ... when the user does ... "

   A use case should capture a good deal of what happens "under the covers" in response to what an actor is doing, whether the system creates new objects, validates user input, generates error message, ... etc.

8. Don't omit text for alternative courses of action.

   Right from the start of use case development, alternative courses of action should be weighed equally with desired action.

9. Don't focus on something other than "what's inside" a use case, such as how you get there or what happens afterwards.

   Pre- and post-conditions should be used only if they are really necessary. If not, keep use cases short and simple.

10. Don't spend too much time deciding whether to use or .

    Choose one mechanism for describing commonality among use cases, and then stick to it.

Robustness Analysis Mistakes

1. Don't violate the robustness diagram rules.

   The purpose of these rules is to get your text into noun-verb-noun format and to help ensure you don't start allocating behavior to objects before you have enough information to make good decisions.

2. Use robustness analysis to help ensure a consistent format for your use case text.

3. Include alternative courses on rubustness diagrams.

4. Use robustness analysis to ensure consistency between class names on class diagrams.

5. Don't allocate behavior to classes on robustness diagrams.

6. Don't include too few or too many controllers.

7. Don't take too much time trying to perfect robustness diagrams.

8. Don't try to do detailed design on robustness diagrams.

9. Make sure that you perform a visual trace between use case text and the robustness diagram.

10. Update your static model.

CHECKLIST

Checklist for systems planning and analysis:

References

• Add ref on OCL ....

Developed in March 2001 by Mark Austin
Copyright © 2001, Mark Austin, University of Maryland