UML Class Diagrams can be used not only for documenting software design, but for documenting software requirements. One of the challenges in writing clear, unambiguous requirements is being precise about what a particular word means. This is especially true with symbolic terms like “quote” or “customer” – where everyone knows what they mean – but they mean different things to different people.
Why Create UML Class Diagrams for Requirements?
One of the first articles we wrote in 2005 provides a very simple class diagram example, and an explanation of why you should use class diagrams to clarify your documents.
In prose, we could also capture the same information as follows:
- The system shall include a representation of customer orders.
- Each order will have a single associated customer, and each customer can have multiple orders. Note that a customer is not required to have any orders.
- Each order will have at least one, and possibly multiple line items. Each line item is uniquely associated with a single order.
- Each line item represents a single product. Note that a product is not required to be represented in a line item. A product can be represented in multiple line items (even within the same quote).
OOA is compellingly powerful as a descriptive tool – it took less time to draw the diagram, and it can be easier to read than the prose.
UML class diagrams, in addition to being potent for communication, can also help with requirements discovery. They provide a clarity and explicitness of understanding that helps you gain insight into the topics being explored.
Getting Started or Getting Refreshed
If you already know UML, or generally know how to draw UML 2 Class Diagrams, you can “test out” of this article, and go to the best, most thorough explanations we know of, courtesy of Scott Ambler.
- UML 2 Class Diagrams – an explanation, in detail, of how and what and why to draw things a particular way
- UML 2 Class Diagram Guidelines – advice on how to make your diagrams consumable and appealing
If your eyes glazed over, that’s ok. There is a lot to absorb. There are a lot of advanced concepts that can be represented in class diagrams, and Scott provides explanations and examples of how to do most of them. If you are new to modeling with UML, or are only interested in what you need to know to document requirements, those articles may be too advanced for now. We’ll try and close the gap. Keep those links handy, both for reference, and for deeper explanations than we cover here. If Ambler’s articles are written to help you be a master craftsman, we want to help you become a journeyman first.
Class diagrams are incredibly powerful tools for anyone doing requirements work. I never wrote about them before, because Ambler already did. And he didn’t leave me wanting more, so I never knew what to write. After a recent conversation with someone new to modeling, I discovered that he did leave a gap. There’s a fair amount of learning you need to do before you can really get the value from his articles. Ambler also addresses both the analysis and design uses of class diagrams.
We will focus exclusively on using UML class diagrams for analysis. So if you are a business analyst or requirements analyst, this will help. If you are a developer, this will help you read the diagrams that analysts create. If you are a product manager, this will help too, but I think you’ll need to do this less frequently than a business analyst would.
We do assume that you are already comfortable using Microsoft Visio, but have not used it for creating class diagrams. You don’t have to use Visio, but the tools in Visio are good ones for creating class diagrams.
Visio Template for UML Class Diagrams
The easiest way to get started is with the default drawing type already available in Visio.
Create a new file, and select the Software category, then scroll down and select “UML Model Diagram” in either US or Metric units. When you do, a number of stencils will automatically load for you. You want to use the UML Static Structure stencil.
These are the shapes that you use to represent objects in a class diagram. You can safely ignore all of the other stuff that Visio provides in the other templates.
The Class
When you drag the “Class” shape onto the page, you get the empty looking box on the left. Visio automatically names it for you as “Class1.” The class represents a concept, entity, item, or object. It is important for analysts to remember that what you are drawing is “how the business thinks about these objects” – not “how developers will implement a representation of the objects.”
There are three areas in each “class” shape. The shape on the right shows that the top area is where the name of the class appears (in bold), the middle section represents attributes, and the lower section captures operations that can be performed by the shape. This feels like describing an implementation or design. The terms attribute and operation certainly sound like programming. UML Class Diagrams may have initially been created to help developers design solutions, that would certainly explain the names. There is still a lot of power to be unleashed – so take it on faith for now – we’ll present some examples that demonstrate the value of class diagrams for analysis.
Imagine that you are thinking about a lamp. Perhaps you are designing an emergency battery backup system, and one of the things you need to think about is how much wattage a lamp requires to operate. The wattage of the lamp, in English, is a characteristic of the lamp. Programmers call it an attribute. For our purposes, the terms are interchangeable.
A lamp can be turned on. That is pretty intuitive. We imagine ourselves turning on a lamp. Actually, all we do is turn a dial (or flip a switch). When we turn the dial, the lamp turns itself on. If we were really playing with language, we might say “When the user requests illumination, the lamp turns on.” We would never use that phrasing for a concept as simple as a lamp, but you get the idea. The operation is something that the object can do. Dogs bark, cats meow, lamps turn on.
When we are creating class diagrams for requirements discovery, we will always use class names, almost always use attributes, and almost never use operations.
A customer, in the diagram element above has an address. The customer also has a credit rating.
The two elements above represent the same information. A product has both price and weight. We also find, during our requirements exploration, that we need to know if a product is available. Perhaps our users need to know if a product is available right now before suggesting it as an up-sell item to a customer. If that is our requirement, we realize that we need to know the availability of the product. You can either include the question “Is it available?” or a single name for the attibute – “Availability.”
It is better to use the word “Availability” for two reasons. First, it is consistent to say “price, weight and availability.” You could achieve consistency with all questions – “What is the price?” “How much does it weigh?” and “Is it available?” But that becomes overly wordy. The second reason for using a single word is to avoid embedding rules in your requirements.
Consider the “Credit Rating” attribute for the Customer object. What we really want to know is if the customer’s credit is good. The definition of “good” will change over time, or may become complex. “Good enough for small purchases”, “Good when putting 20% down” are examples of the definition of “good” becoming complex. Or maybe you’re loaning money, and you can improve your profits with notions of “pretty good” and “really good.” You will create business rules to define what you mean by good. You happen to know that those rules will reason about the customer’s credit rating, so you should capture that value.
You could but should not represent the notion of “Is Credit Good?” with an operation:
You end up specifying design here – however unintentionally. Depending on how you interpret this, you are either saying “Customers are responsible for determining if their credit is good” or “The credit worthiness of a customer is determined without considering anything other than the customer.” While precise for programmers doing design, this is a pretty ambiguous thing to document in an analysis. By adding this operation, you are not providing unambiguous insight into how the business thinks about customers. So don’t do it.
Next Up
In our next article on UML Class Diagrams for analysis, we’ll look at relationships between classes.
If there’s something in particular you’d like to see explained, add a comment below and we’ll either fold it into the series or answer in the comments. And remember – you can subscribe to the comments for any article, just click the link.
Uncovering Requirements With UML Class Diagrams Part 2: Simple relationships between objects or entities.
Latest Articles
Comments on all Articles
