  | 1 of 70
 |   |
| | 1 of 70
| |
Next we turn to more formal documentation that you can expect to show outside your team and probably to retain for the lifetime of the project.
We will employ UML notation for this.
UML notation has quickly become an industry standard
with applications outside of “traditional” software engineering: e.g., DBs
UML Diagrams
UML provides a number of different diagrams
package diagrams
We’ll look eventually at the ones shown in italics, starting with class relationship diagrams.
Diagramming in Context
The diagrams are part of an overall documentation strategy.
The purpose of that strategy is communication.
We don’t usually draw diagrams to stand by themselves.
Instead, like the diagrams that appear in, say, your textbook, each one is intended as part of a larger document, much of which will be explanatory text.
Furthermore, we draw diagrams for the same reasons we write sentences and paragraphs, to communicate some specific idea.
If a diagram is too complicated to be understood, it’s no more use than a sentence that is too complicated to be understood.
If a diagram is too vague to convey any definite meaning, it has no more value than an equally vague sentence.
The success or failure of a diagram lies entirely in its ability to communicate what the author intended.
The diagrams are actually the representation of a formal “language” and are expected to make statements that are meaningful according to the rules of that language.
A class relationship diagram describes the types of objects in the system and selected static relationships among them.
The relationships can be
generalization (e.g., a Librarian is a specialized kind of Library Staff)
association (e.g., a Patron may have up to 20 Publications checked out at one time)
Perspectives
A diagram can be interpreted from various perspectives:
Specification: focus is on the interfaces of ADTs in the software.
Implementation: describes how classes will implement their interfaces
The perspective affects the amount of detail to be supplied and the kinds of relationships worth presenting.
A class can be diagrammed as
We’ve already seen the three-part form of this.
But in the course of writing a full set of documentation, a class might appear multiple times in different diagrams. It could be distracting to list out all of tha attributes and operations every time it appears.
Instead, you can use the simpler name-only form when discussing a class whose attribute and operation details are given elsewhere, particularly if the attributes and operations of the class were not relevant to the idea you wanted that diagram to communicate.
Even an Empty Section has Meaning
Note that these are not equivalent:
The left diagram says that we aren’t discussing the attributes and operations.
The right diagram says that this class has no attributes and operations.
Attributes are given as
visibility name: type = defaultValue
Only the name or type is required. The others may be added when relevant:
Only for implementation perspective.
When you are only talking about concepts or interface specifications, the idea of a “private” anything is irrelevant.
Attributes are usually single values.
Operations are given as
visibility name (parameterlist) : return-type
Again, the amount of detail depends on the perspective (and on how much has actually been decided)
A class (the “subtype”) is considered to be a specialized form of another class (the “supertype”) or, alternatively, the supertype is a generalization of the subtype if
conceptual: all instances of the subtype are also instances of the supertype
specification: the interface of the subtype contains all elements of the interface of the supertype
The subtype’s interface is said to conform to the interface of the supertype
implementation: the subtype inherits all attributes and operations of the supertype
Diagramming Generalization
The UML symbol for this relationship is an arrow with an unfilled, triangular head.
Read this arrow as “is a specialization of”, “is a kind of”, or “is a”. (The latter can be a bit ambiguous however, as we might also say that Webster’s Dictionary “is a” Book, but that’s not a generalization relationship.
We infer from the relationship that books and magazines have titles and dates of publication and that we can get their content. However, not all publications have ISBNs.
Multiple Specializations
Some classes may participate in multiple generalization relationships. The arrows are grouped together to indicate related, mutually exclusive, divisions:
An association is any kind of relationship between instances of classes.
In a conceptual perspective, associations represent general relationships. In a specification perspective, associations often denote responsibilities.
Diagramming Associations
Associations are shown as lines connecting classes.
Plain associations like these are not particularly useful.
This one tells us, for example, that some spreadsheets have some kind of relationship with some cells.
Decorations
We make the associations meaningful by attaching various decorations.
Relationship Names
Most important of these are the decorations that name the relationship being shown.
Names: Names of relationships are written in the middle of the association line.
Good relation names make sense when you read them out loud:
They often have a small arrowhead to show the direction in which direction to read the relationship, e.g., expressions evaluate to values, but values do not evaluate to expressions.
Roles
Roles: a role is a directional purpose of an association.
Roles are written at the ends of an association line and describe the purpose played by the associated class in the relationship.
E.g., A cell is related to an expression. The nature of the relationship is that the expression is the formula of the cell.
Roles and Attributes
Roles versus Attributes
When should you use attributes within a class and when should you use associations with role names?
Lean towards using associations when the relationship is not one-to-one.
Use associations when you want to target the attribute’s class for other associations (e.g., the “evaluates to” association in the earlier diagram.
Unnamed Associations are Useless
As a rule, I would argue that every association should have either a name or roles
Unnamed Associations are Useless (cont.)
Not everyone agrees.
In other words, this
would default to
Multiplicity indicates how many instances of a class participate in the relationship.
Multiplicity is encoded as:
k: Exactly k instances (where k is an integer or a known constant)
k..m: Some value in the range from k to m (inclusive)
*: Denotes the range 0..infinity. Can also be used on the upper end of a “..”, e.g., 1..* means “at least one”.
Diagramming Multiplicity
This diagram above indicates that
each spreadsheet contains any number of cells, but that
a cell is contained within exactly one spreadsheet.
Each cell contains exactly one expression and one value, and these values and expressions are not shared with other cells.
Navigability arrows indicate whether, given one instance participating in a relationship, it is possible to determine the instances of the other class that are related to it.
The diagram above suggests that,
given a spreadsheet, we can locate all of the cells that it contains, but that
Given a cell, we can obtain the related expression and value, but
Navigability and Role Names
In perspectives and relationships where the role names are attribute names, we would not have a role name for an un-navigable direction of an association.
Hence, we have no role name naming the cell related to a value or expression.
Navigability and Perspectives
Navigability is probably not useful in most conceptual diagrams.
In a specification/implementation diagram, if no arrows are shown on an association, navigability defaults to two-way.
For example, in a specification perspective, this
defaults to
Certain kinds of associations occur so frequently that they are given special symbols that replace names and (often) role labels.
Denoted by an arrowhead drawn as an unfilled diamond, aggregation can be read as “is part of” or, in the opposite direction as “has a”.
This diagram suggests that cells are part of a spreadsheet and that an expression and a value are each part of a cell.
Aggregation Details
The multiplicity at the arrowhead defaults to “1”.
Aggregation is almost never named and roles are only used if the attribute name would be unexpected.
There is a lot of variation in deciding when to use use aggregation.
Example: Should This Be Aggregation?
For example, this diagram tries to circumvent our rule that attributes are single-valued by having a “single” set as an attribute.
That would be OK in an implementation perspective (i.e., in a design model),
but not in an earlier model/perspective where it prematurely suggests a data structure.
Example: Should This Be Aggregation? (2)
Example: Should This Be Aggregation? (2)
This alternative would also be OK in a design model.
Example: Should This Be Aggregation? (2)
This alternative would also be OK in a design model.
But it’s terrible in a conceptual perspective and uncomfortable in a specification perspective.
Example: Should This Be Aggregation? (2)
This alternative would also be OK in a design model.
But it’s terrible in a conceptual perspective and uncomfortable in a specification perspective.
If I read this as “books can be part of a patron”, I get a mental picture of books being surgically implanted into people. I would not accept that in a domain or analysis model.
Example: Should This Be Aggregation? (3)
This one is no better in the earlier perspectives.
Example: Should This Be Aggregation? (3)
This one is no better in the earlier perspectives.
Example: Should This Be Aggregation? (3)
This one is no better in the earlier perspectives.
I’m starting to feel like I will never visit a library again.
Example: Should This Be Aggregation? (4)
So, for conceptual or specification perspectives, I’d avoid aggregation in this case and fall back to a general association.
Composition is stronger form of aggregation. It implies that the “lifetime” of the parts is bound to the lifetime of the whole.
The usual test to see if composition applies is to ask, “if I delete/destroy the container, do the parts go away as well?”
Composition is denoted by an arrowhead drawn as a filled-in diamond.
Composition Example
This diagram suggests that destroying a cell would also destroy its value and formula. That makes sense if the cell does not share those components with other objects.
However, destroying a spreadsheet does not necessarily destroy its cells.
A qualified association describes a situation in which one class is related to multiple instances of another, but the collection of related instances is “indexed” by a third class.
A class A depends on another class B if a change to the interface of B might require alteration of A.
A dependency is indicated by a dashed line ending at a navigability arrow head.
Dependencies have little use outside of an implementation perspective.
Dependency Example
This diagram shows a system that has been decomposed into three major subsystems.
The Model is the core data – the stuff that this program is really all about.
The View is the portion of the code responsible for printing or drawing portrayals of the model data - for example, code to render graphics on a screen as part of a GUI.
The Controller is the portion of the code responsible for accepting interactive inputs (mouse clicks, key presses, etc) and responding to them.
MVC
The dependencies shown here are the defining characteristic of the MVC approach to user interface design:
MVC
The dependencies shown here are the defining characteristic of the MVC approach to user interface design:
MVC
The dependencies shown here are the defining characteristic of the MVC approach to user interface design:
the controller depends upon, and therefore can make calls upon, the model
MVC
The dependencies shown here are the defining characteristic of the MVC approach to user interface design:
the controller depends upon, and therefore can make calls upon, the model
Neither the view nor the model depend on the controller.
MVC
The dependencies shown here are the defining characteristic of the MVC approach to user interface design:
the controller depends upon, and therefore can make calls upon, the model
Neither the view nor the model depend on the controller.
The view depends on the model
MVC
The dependencies shown here are the defining characteristic of the MVC approach to user interface design:
the controller depends upon, and therefore can make calls upon, the model
Neither the view nor the model depend on the controller.
The view depends on the model
MVC
The dependencies shown here are the defining characteristic of the MVC approach to user interface design:
the controller depends upon, and therefore can make calls upon, the model
Neither the view nor the model depend on the controller.
The view depends on the model
But the model does not depend on the view.
Why MVC?
The advantage of this interface design is that we can radically change the user interface without altering the core computations (the model).
We won’t use these as often, but you should be able to recognize them.
Parameterized Classes
Used to represent templates and similar concepts.
Constraints
Constraints can be added almost any place by writing them within brackets.
Stereotypes
Stereotypes are an extension mechanism built in to UML. Written within <<…>>, these are labels used to indicate that you are deviating slightly from the standard interpretation of a UML construct.
For example, an interface is a collection of related operations.
Satisfies / Realizes
Another specialized association, this is actually a combination of dependency with the arrowhead of generalization.
In theory, you can use almost any drawing tool.
In theory, you can use almost any drawing tool.
But general-purpose tools offer you more opportunities to mess up
In theory, you can use almost any drawing tool.
But general-purpose tools offer you more opportunities to mess up
Better to use a tool that “understands” UML
On our systems, we have
In theory, you can use almost any drawing tool.
But general-purpose tools offer you more opportunities to mess up
Better to use a tool that “understands” UML
On our systems, we have
dia, an open-source product (Windows & Linux)
In theory, you can use almost any drawing tool.
But general-purpose tools offer you more opportunities to mess up
Better to use a tool that “understands” UML
On our systems, we have
dia, an open-source product (Windows & Linux)
In theory, you can use almost any drawing tool.
But general-purpose tools offer you more opportunities to mess up
Better to use a tool that “understands” UML
On our systems, we have
dia, an open-source product (Windows & Linux)
Visio, a commercial product from Microsoft (Windows)
In theory, you can use almost any drawing tool.
But general-purpose tools offer you more opportunities to mess up
Better to use a tool that “understands” UML
On our systems, we have
dia, an open-source product (Windows & Linux)
Visio, a commercial product from Microsoft (Windows)
In theory, you can use almost any drawing tool.
But general-purpose tools offer you more opportunities to mess up
Better to use a tool that “understands” UML
On our systems, we have
dia, an open-source product (Windows & Linux)
Visio, a commercial product from Microsoft (Windows)
omit visibility markers
In theory, you can use almost any drawing tool.
But general-purpose tools offer you more opportunities to mess up
Better to use a tool that “understands” UML
On our systems, we have
dia, an open-source product (Windows & Linux)
Visio, a commercial product from Microsoft (Windows)
omit visibility markers
In theory, you can use almost any drawing tool.
But general-purpose tools offer you more opportunities to mess up
Better to use a tool that “understands” UML
On our systems, we have
dia, an open-source product (Windows & Linux)
Visio, a commercial product from Microsoft (Windows)
omit visibility markers
In theory, you can use almost any drawing tool.
But general-purpose tools offer you more opportunities to mess up
Better to use a tool that “understands” UML
On our systems, we have
dia, an open-source product (Windows & Linux)
Visio, a commercial product from Microsoft (Windows)
omit visibility markers
Data Entry Rather than Direct Formatting
Exporting the Final Product
As a general rule, you edit and save your documents in the tool’s native file format
Then export as graphics to be pasted into your documentation
Use vector graphics formats whenever possible
Best choice depends on what your document tool can import
Remember, we don’t draw diagrams just for the sake of drawing diagrams. Diagrams should contribute to an overall narrative describing our model. (An example will be shown in the next set of notes.)
As we construct this narrative, we should merge the attribute and operation information from our isolated class diagrams into the diagrams so that no information is lost.
Every class should be shown with its full set of known attributes and operations at least once.
Generally, we would show the full class details once only, unless the attributes and operations are particularly relevant to understanding the narrative for multiple diagrams.
Technically, an isolated class diagram is a class relationship diagram. But such an un-informative choice is, at best, a missed opportunity.
Try to find a meaningful way to relate it to other classes in the model.
Each diagram should tell a reasonably cohesive story and should contribute to the surrounding text.
Beware of massive diagrams that try to pack too much into a single picture. That’s every bit as bad as trying to cram all the ideas of a paper into a single paragraph.
| | 1 of 70
| |