5.4 Documenting Classes and Attributes


5.4.1 Diagramming Classes and Attributes

Figure 5.4 shows how classes are shown on a class diagram as boxes divided into three compartments.

Class name.

The top compartment identifies the class: It contains the class's name along with an optional number and abbreviation ("key letters"). UML, as opposed to Executable UML, allows only for the class name.

Class number.

A class may have a sequential number that provides the ordering for the descriptions. This is optional and some tools may provide an option to suppress its display.

Class abbreviation (key letters).

A class may have a small abbreviation used as a shorthand to refer to the class, especially in class actions. By using the abbreviation, we can maintain a readable name in the diagram while keeping actions succinct. Like the number, it is optional. If the abbreviation is not shown, it is assumed to be the same as the class name.

Attribute compartment.

The middle compartment contains the attributes and their types. In addition, attributes may have an initial (default) value.

Operation compartment.

The operations compartment contains operations performed by the class. We describe operations later when we discuss actions and procedures.

Suppressed display of diagram components.

UML allows parts of a class box (e.g., the attribute types, class numbers, attributes, and operations) to be suppressed in the display of a diagram. We will suppress some information on some diagrams in this book, such as the class box in Figure 5.5, to make the diagrams more readable. But we will suppress the information only when it is not essential to the example at hand.

Figure 5.5. Class Box with Types and Tags Suppressed

graphics/05fig05.gif

5.4.2 Class Descriptions

A model without descriptions is like a dictionary without definitions for the words. Even the best class names can be confusing without context.

A class description is a short, informative statement that allows one to tell, with certainty, whether or not a particular thing is an instance of the class as conceptualized on the class diagram. Class descriptions include descriptions of each of the class's attributes.

Write a description for each class in the model. Start drafting descriptions early in the modeling process this will frequently tell you if you are getting off track. Here are some informal technical writing hints that we have found helpful in producing good descriptions.

Domain statements vs. model statements.

In writing a description, make statements about the reality being formalized in the model as well as statements about the model constructs themselves. To allow the reader to distinguish between these two kinds of statements, we have found it helpful to establish a typographical convention: Use an initial capital letter for all words in a class name, lower case when referring to things in the domain.

Basis of abstraction: inclusion criteria.

Describe the ways in which things in the domain that have been abstracted as a class are alike (that is, inclusion criteria).

Customer

A Customer is an individual or organization that has placed orders for books and other products offered by the store.


Basis of abstraction: exclusion criteria.

Establish exclusion criteria if there are things that are not abstracted into this class.

A Customer must have purchased books; a user who simply browses to the site is not considered a Customer until he/she places an Order.


Background information.

Sometimes a certain amount of background information enhances the class description.

Customers remain active for six months after their last order. Active customers receive periodic e-mail reminders of sales and can be eligible for discounts based on how much they have previously purchased.


Technical writing standards.

Finally, standard technical writing practices apply to class descriptions: A class description should be written in short declarative sentences using the present tense. Avoid vague or ambiguous terms. There are a number of further examples of class descriptions contained in the appendices. Those we judge most successful preserve the theme of the information as a reflection and abstraction of the reality of the domain.

For many more good examples of class descriptions, see Leon Starr's books [2] and [3].

5.4.3 Attribute Descriptions

Each class description includes short, informative descriptions that tell, for each attribute, how the attribute reflects the real-world characteristic of interest. Some suggestions for preparing the attribute descriptions are given below together with a few examples.

The manner in which we write the attribute description depends on the kind of attribute.

Descriptive attributes.

The attribute description for a descriptive attribute states what characteristic, possessed by all things, is being captured in the model by this attribute.

Magnet

desiredCurrent: ElectricalCurrentMeasurement

Reflects the current expected to be delivered to the magnet. This is in contrast to Magnet.actualCurrent. When actualCurrent equals desiredCurrent (within a tolerance) then the apparatus is stable and the experiment can begin.


Publisher

address: MailingAddress

The address at which the publisher receives mail. It can be a legal or common-use street address recognized by the post office, or a post office box.


ProductSelection

unitPriceOfSelection: Currency

Represents the unit price of a product added to an Order at the time the product is selected and added to the order. This attribute is initialized with Product.unitPrice but is kept separately so as to capture the price the customer actually pays even if the actual product price changes.


Naming attributes.

The attribute description for a naming attribute should specify the form of the name (if relevant); the organization that assigns, registers, or controls the names (if relevant); and the extent to which the attribute forms a part of a unique name. For example, it is important semantic information that members of the Screen Actors Guild must have unique names.

ScreenActor

screenName: PersonalName

The name the ScreenActor uses for professional work. Members of the Guild are required to have unique names to encourage "brand identification" for each member. Names are considered different if they differ in any way. Hence, "Fred O. Jones" is different from "Fred Jones."


Referential attributes.

Referential attributes provide facts about links. For example, an order may have a customer attribute that refers to the customer who made the order. These attributes are not generally required as this information is implicit in the association. We take up this topic in the next chapter, Chapter 6: Relationships and Associations.

Descriptive Attribute or Referential Attribute?

It is sometimes difficult to decide if an attribute is descriptive or referential because it depends on context. For example, weight is descriptive until you consider a context wider than the earth (e.g., the solar system). Weight then becomes dependent on more than just the object being weighed. The situation is similar with color, once you consider anything other than a standard white light source, or you're attempting to capture specifications of colors in a manufacturing process.

In fact, there are no attributes that are truly "intrinsic"; they just seem that way because the context is held constant.

This observation, due to Conrad Bock, can be turned around: A domain de-fines a context for your model and only in that context can you determine whether an attribute is descriptive or referential.



Executable UML. A Foundation for Model-Driven Architecture
Executable UML: A Foundation for Model-Driven Architecture
ISBN: 0201748045
EAN: 2147483647
Year: 2001
Pages: 161

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net