The different types of model elements in the UML 2.1 specification do not have a description property. Initially this looks like an obvious oversight because a textual description is one of the key bits of information of most elements in a model. It would be unthinkable to have classes or components in any serious model without descriptions.

The different types of model elements in the UML 2.1 specification do not have a description property. Initially this looks like an obvious oversight because a textual description is one of the key bits of information of most elements in a model. It would be unthinkable to have classes or components in any serious model without descriptions.

However, on closer examination, the lack of an explicit description field is not an oversight. All UML 2.1 model elements own zero or more comments, textual annotations that are model elements in their own right. A UML 2 comment element "carries no semantic force, but may contain information that is useful to a modeler". 

Therefore, in theory, we could use an owned comment to hold the description of a model element. 

Unlike a description property, a comment has a graphical representation, that of a rectangle with a folded top right-hand corner (the traditional note symbol). This means that a comment used as a description can easily be shown on a diagram alongside the element it describes.

However, if an element owns more than one comment how do we know which one holds the description of the element? We could give the comments holding the description a name that we could recognise, possibly the same name as the element that owns the comment with a Description suffix. For example, the description for a Sale class would be in the comment called SaleDescription. Unfortunately, although a comment is an element in UML 2, it is not a named element and therefore cannot have a name. Names of Model Elements in UML 2.1 Models discusses the decision in UML 2 to allow elements without names a little more. In many cases, being able to refer to a comment by a name would be really helpful.

Fortunately, in this case, we can do better. As an element a comment can be given a stereotype, so we could give all the comments that hold the description of their owning elements  the stereotype <<description>>.  This is much better than the name solution because by using a stereotype we are further defining the type of the comment and that is precisely what we want to do. We now have description comments as a type of element in our models.

This approach of using stereotyped comments is more flexible than a single description property defined for an element. There are many times when a model element needs more than one kind of description. Looking through the UML 2.1 specification itself, we often find that there is a single sentence that introduces a concept.  For example, a comment is introduced as "A comment is a textual annotation that can be attached to a set of elements".

Then after a list of generalizations, we find a longer description. For example the description section for a comment states, "A comment gives the ability to attach various remarks to elements. A comment carries no semantic force, but may contain information that is useful to a modeler. A comment can be owned by any element".

So far the two descriptions of the comment have been informal. A further section titled semantics presents a complete formal description of what the element means. Finally, although unfortunately, missing from the UML 2.1 specification but present in the old UML 1.x specifications is the entry for the element in a glossary of terms.

Therefore, a model element  in a UML specification can have up to four different descriptions. A single description property would not cope very well if we have similar requirements for descriptions in specifications generated from our own models. However, with the stereotyped comment approach, we can define four stereotypes for comment elements to use in our models,  <<introduction>>, <<description>>, <<semantics>>, and <<glossary term>> for example.

The downside of using this approach, however, is that we have to create all these comments for the elements in our models. Here is where UML modelling tools could help by enabling a user to specify what kinds of owned comment they want to use in a model and make it easy to fill them out for each element. For example, after a user has chosen to use <<introduction>> and <<description>> comments in a model, the tool could add tabs or fields for those comments to the usual element property inspector view, with a toggle button to make it easy to show or hide the comment as a note symbol on the diagram.

Unfortunately, Borland Together 2007 uses a different approach. It adds a description property to each element. This is better than nothing but not nearly as flexible and elegant as the approach outlined above. The approach above can be approximated by defining additional element properties for each of the comment types using the UML profile feature and running an in-place QVT transformation that populated note symbols with the contents of those properties. An ocl-based model audit can be defined to check that note text is up to date with the contents of the relevant property. Of course, the audits need to be run to be of use so a regular or continuous integration environment might be needed to ensure that they are.

Follow me on Twitter...