The Coad Letter: Modeling and Design Edition, Issue 82, Description Class Archetype

By: Coad Letter Modeling Editor

Abstract: In this issue, we look at one of the archetypes for color modeling, descriptions.

Hi all

Phew! It's been one of those months. First working with a team building a domain object model in color in the United Arab Emirates, then a visit to TogetherSoft HQ, in Raleigh, North Carolina and now at the start of a week working with a team in Bologna, Italy ... and time for another issue of the Coad Letter.

This month an in-depth look at one of the four class archetypes used in the 'modeling in color' technique, the Description archetype. People often seem to become confused by the Green and Blue archetypes. I hope this month to help clarify the differences between the two a little more. The article assumes a basic knowledge of modeling in color. A short introduction to 'modeling in color' can be found in CoadLetter #68. A slightly longer discussion can be found in chapter 1 of the Java Modeling in Color with UML book that can be downloaded from

Have fun


Stephen R Palmer

ps There's a NEW presentation by Peter Coad, "Modeling Faster and Better with Archetypes," now available for downloading at Complete story re: TogetherSoft's lively, informative, and utterly pragmatic services now posted at

Description Class Archetype

Got the Blues?

Color modeling provides a higher level of abstraction above that of objects and classes. We call this higher abstraction, class archetypes.  In color modeling, all significant Problem Domain classes belong to one of four class archetypes. A class archetype defines typical sorts of attributes, operations, associations and interactions for classes belonging to that archetype. The archetypes are color-coded and the four colors help patterns between classes of each archetype stand out within an object model.

One of the four class archetypes is the blue Description archetype. This is used to represent objects that might appear as entries in some sort of catalog. The descriptions of car models in a car dealer's showroom catalog are a good example. The catalog entries contain values that apply to a large subset of real world objects, actual physical cars in our dealership example.


What are the typical sorts of attributes we might discover for a class belonging to the Description Archetype? A type code or name is obvious. For a car dealership catalog this would be the model name or number of the car e.g. 528i in a BMW dealership or Civic in a Honda dealership.

We often need to have a longer textual description of the item so we have a description attribute for that. We can use this attribute to provide the two or three lines of marketing teaser in the catalog extolling the virtues of a BMW 528i or Honda Civic.

The next attribute suggested by the Description archetype is the number of the entry in the catalogue. Then follows a set of attributes holding default values or values common for all entities (actual physical cars) described by the catalog entry. For example, wheel type (steel or alloy), interior type (cloth or leather), air-conditioning (included or not). Individual cars described by the blue BMW 528i or Honda Civic object may have the default value for these attributes or a customized value.


So much for attributes! What about operations? We'll come back to assessWithPluginElseDefault() later. AssessAcrossPPT's is suggesting we might find some operations that calculate some aspect of the performance of the entities described. In our example that might be an operation to calculate the average sale price of all objects representing the actual physical cars described by one of our blue catalog entry objects. In other words, what was the average sale price of all the 528i's we have sold? The suggested findAvailable() and calcQtyAvailable() operations we could translate to finding a car of a particular model that is ready to be sold or to counting the number ready to be sold.


The usual place to find a class of the blue Description class archetype is associated to a class of the green Party/Place/Thing class archetype. In our example we have the blue Model description class associated with the green Car thing class. However, as described in CoadLetter #68, we will often find the level of specificity provided by the full Domain Neutral Component pattern is not needed. For example, we would be interested in tracking the individual cars sold by our car dealership but we would not be interested in tracking each individual potato that a grocer sells - just the quantity of potatoes. Therefore we drop out the class archetypes we do not need from the general pattern until we have a model with an appropriate level of specificity. The result of this process is that often a blue Description archetype ends up associated to a yellow Role archetype or a pink Moment-Interval archetype.

There are also times when we truly want to describe different types of yellow Role and pink Moment-Interval archetypes and it feels right to connect a blue Description directly to a yellow Role or pink Moment-Interval. An example is an employment Moment-Interval where there are different types of employment - full-time and part-time for instance.

Martin Fowler in his analysis pattern book [Fowler] splits classes into two layers: operational and knowledge. We could color the classes in Martin's knowledge layer blue. It would indeed seem we can connect a blue class to describe any archetype - connecting to a green is the most likely, pink is the next likeliest. In my experience, connecting directly to describe a yellow Role is much less frequent and is more often the result of dropping unnecessary classes from a more general DNC inspired model shape. However, the question of whether we are connecting to describe or connecting because we are dropping unnecessary classes is one probably best debated over a few drinks after work; the end result is much the same.

Trade off between blue and subclassing green

When talking about description archetypes, we often find ourselves using the 'type' word. A BMW 528i is a type of car; the actual BMW 528i sat on the driveway of one my friendly TogetherSoft sales reps is an object, example, specimen or instance of that type. Surely the traditional object oriented way to represent different types is to create subclasses? There are some subtle differences and some design trade-offs to be made. Let's look at the trade-off's first.

Using a blue Description class to represent different types we can very easily create a new type in a running system by creating a new instance of our Description class and configuring its attributes accordingly. Using subclassing we need to code a new class and deploy it before we could create objects of the new type; not too bad in Java but definitely not so easy in C++.

However, blue Description classes have their limitations; if different types actually have different attributes instead of just different values of the same attributes it quickly becomes messy or over complicated to use a Description class and subclassing is usually the better option. The same is true when different types need different operations; if only the algorithm of one or two operations differ we can use the plug-in strategy described below.

To summarize: A blue Description class is useful when the objects it describes have common attributes but subsets have different default values of those attributes. However, when subsets of the described objects have differing quantities and types of attribute and operations then subclassing is the better approach.

Of course, the optimum model is often a mix of the two.

The Blue Plug-in Point

We can offset the need to subclass just to get a slightly different algorithm for an operation by defining a plug-in point and delegating to a plugin class if one is provided. This is where the assessWithPluginElseDefault() operation suggested by the Description archetype comes into play. If the plug-in class is provided this operation invokes the equivalent operation on the plug-in class. When the plug-in is not present the operation uses a default algorithm instead.

The plugin can also be used to change the algorithm over time without having to make changes to existing code.

One final note: an oddity of human behavior I have observed a number of times (especially in the USA for some reason) is to call Description classes, Detail classes by mistake and start a train of thought that understandably leads to confusion between what is blue and what is green. Strange but true; it has happened so often in our modeling workshops I'm no longer surprised when it happens now.  And on that note ... that's it for this issue.


[Fowler] Martin Fowler, Analysis Patterns, Addison Wesley 1997

Server Response from: ETNASC03