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.
I think this post of yours is very relevant. Sometimes we should cross the psychological barrier that only a subset of UML diagrams should be meant for customer consumption.
In relation to the beginning of the post, I recall the idea of literal modelling and the book “Enterprise Patterns and MDA: Building Better Software with Archetype Patterns and UML” by Jim Arlow and Ila Neustadt. They convey the idea of literal modelling and use it throughout the book to describe the business archetypes.
They also note that even a person who does not know the formality of UML will understand most of the diagrams if these have descriptive text. It sure is a powerful form of communication.
In the first edition of Applying UML and Patterns, Craig Larman calls these diagrams “conceptual models”. A couple of guidelines from Larman:
“If in doubt, make it a separate concept.” – In other words, prefer concepts over attributes.
“It is better to overspecify a conceptual model with lots of fine-grained concepts than to underspecify it.” – When there are “implied” concepts, explicitly model them.
Another important thing to recognize is that conceptual models are an explication tool.
C’mon people, these aren’t UML Classes, they are entities of a Logical ER Data Model.
UML is great for for modeling component/OO software. Software does stuff, so a Class without operations is just simply incomplete. If you want to model data at rest, use a data model, and augment it with business rules.
(I know, I know, some people will say they prefer Class diagrams over ER diagrams when modeling data, but I have never heard a good reason why…any one got one?)
Dave, you can use either kind of diagram to model concepts and their associations.
Wikipedia states:
“An Entity-relationship model is used in modern database software engineering to illustrate the logical structure of a database.”
Yet, as you wrote, you can model concepts, not just database entities, in an ERD.
Similarly, though developers use class diagrams to model software classes, you can model concepts in a class diagram.
By the way, UML has shifted from calling them “class diagrams” to calling them “static structure diagrams”, precisely because they are useful for modeling more than just classes. Concepts and associations are certainly a form of static structure.
Thanks guys, both for continued participation here and for the healthy debate!
Dave – in addition to Roger’s citation of Wikipedia, here’s how Scott Ambler teases the two notions apart:
Personally, I feel that there is an important distinction between “What I’m trying to represent” and “how I’m going to represent it.” As an OO programmer, I expect significant overlap between the two, but not perfect alignment in all cases. Even though you are making a distinction between the logical and the physical data models, they are still both representations of “what” and not representations of “why.”
When using a class diagram (or, as Roger points out – a static structure diagram) for analysis, you are building a conceptual model. As Ambler also points out in his article, these can be created either before or instead of a logical data model.
I’m working with a COTS (customized off-the-shelf) software vendor right now who’s LDM does not at all represent the conceptual view of the business. This will end up being a source of additional expense for the vendor (and their clients) over time. Regardless, my current role is to validate an understanding of what the business needs – and I’m using class diagrams. The vendor is capable of translating the business view into his implementation view. The business should not be expected to translate in the opposite direction. Both the business and the vendor can utilize this class diagram to do that. Only the vendor would be able to use their logical data model.
That’s a long winded way of saying I prefer the class diagram to an ER diagram because I want to explicitly separate “This is what we need” from “Here’s how we provide it.”
OK, you can but why? And I think you can define entity using the word concept, and vice-versa.
I am just saying ER diagrams are good for data, and UML is good for the software that uses the data, and people should know that. In that case, I still want to hear a good reason to use UML for data requirements over ER diagrams, other than that you can…
Scott, just saw your comment…
You can certainly produce a bad ER model; or is it a generalized meta-model the vendor uses? That is handy when you can support different clients’ business without having to change the model.
…but I will take this as an answer I could expect; if class diagrams work better with the involved business people, then that is the best reason to use them. I know other people who run screaming from either type of model, but love Process Models, so you have to use what works best.
Hey David, thanks (twice) for responding.
In my particular example, they have a “bad ER model” in my opinion as a technologist, because they developed a schema that does not “closely enough” (my opinion) reflect the concepts in play. I would have designed it differently. I can also see, in conversations with them about future unanticipated (but predictable) uses, that they will have to do more work to support those needs.
Reviewing a logical model of how they represent data did not provide me with insights into the uses or interpretation of the data. It provided me with insight into how their implementation was done.
I don’t necessarily disagree with you about models created for the purpose of design and implementation. I subscribe to the “many models” school, and will happily draw whatever makes the most sense in a specific situation.
I’ve been having success over the last year in using fact models to drive teams to common use of terms and language. And I’ve had success for several years in using class diagrams to validate an understanding of the domain with subject matter experts.
I’ve also seen the same thing you have, with people running screaming. :)
I do not believe that a class diagram “stands alone” but I have found it to be consistently effective when collaborating and “talking to” a diagram with SMEs.
There is one exception to that. I have included snippets of class diagrams within requirements documents to illustrate points. For example, I might show a small diagram that highlights the relationships between a sales order, an order item, and a product. This makes it much easier to express, for example, a requirement for distributing (or allocating) a discount to an order across the order items (for revenue recognition purposes).
Man – this is a long way round and almost impossible to scale.
Just think, how long would it take you to teach this to 1000 business users?
My guess is that you would not only fail to get the concept accross, but that you would spend your life supporting the user population and never achieve a best practice library for the business.
Have a look at the video on my web site – http://www.processmaster.com
It puts everything you are doing above into a simple tool, which can be learned in a short video – and uses BPMN, which is the most suitable stencil for normal people.
And the model can be converted over to UML (or any other model) with an adaptor if needed.
You are an expert, and you do know your stuff, but educating people in this way only works for people with basic expertise – you have to go for a media solution if this is to be taken to the masses…………..even a bad video is better than a good document.
Again; congratulations on an excellent paper.
My comments of your paper 5 cover the discussion on classes vs ERD.
I have one reservation. The title is ‘Uncovering Requirements with UML class diagrams’.
The articles give a very clear of what Classes are and how to draw and interpret them. However, this is all syntax of classes. It would have better been called ‘How to work with UML class diagrams when you begin Uncovering Requirements’.
There are a number of key semantic concepts that you clearly missed.
– A computer system should model the business that it lives in as closely as possible. Then it is more maintainable. If the users think about changes, they will often reject the big ones before asking, because they sound too complicated. If the match between business and system is bad, they may have thrown out an very simple change, without even bothering to ask. At the other end of the scale, they will fight furiously to get what is a very simple business change, even when it has been explained that the system can NOT ever support that feature without a complete rewrite.
– The class model is always morer static than the dynamic use case model. Hence, there is a stable base to use when discussing future changes to the system. It usually restricts most of the changes to just a rewrite of a use case or two and possibly an extra feature on a couple of classes. This is why, it is even more important for the classes to be a close map to the business; yet BPMN deals with only the identification and understanding of what are essentially use cases.
I like to start my business model of a system, with a class or object model of the ‘Mission Statement’ for the proposed project. It is usually stated in terms of 4 or 5 classes and some activity that they want to involve them in. This activity is then either embyonic use cases or procedures on these classes. Use cases when defined, will be implemented as application controllers, which if you think of sequence diagrams, call procedures on the classes.
So the whole mission statement can be mapped with surprising detail, for a first step, as a class diagram, with links (associations) laying out the roads that they use cases must follow. With NO controllers (use cases) identified at this stage, the busness classes will appear to link to objects that are real people; these are embryonic actors. Again, it does NOT matter whether we have just classes, or distinguish instances of classes, like identifiable people in class staff; this will sort itself very rapidly as the classes get more clearly defined.
However, the first diagram we draw can actually capture a simple view of the whole of the project to a level that the business should have really clear.
If we start with process diagrams or use cases, you may already be ahead of the business’ thinking. Even if they have thought this through a bit, I will bet that ir is more liekly to change that the simple class diagram.
Now we are beginning to ‘Uncover Requirements’. Dont forget that a few requirements lie in the goals and branch points to alternative paths in use cases. However, the classes should hold a lot more:
– invariants on the class
– constraints on the attributes
– pre-conditions on the procedures
– post conditions on the procedures, if the algorithm to be used is dictated by the business
– constraints on the associations; multiplicity, optionality, qualifiers and other constraints.
Having both use cases and classes shows where the rules fit in and gives their context. The diagrams can provide a good ‘Requirements List’ in pictorial form (worth a thousand words and al’ that!)
Gil
I always seem to have second thoughts. A quick re-read of what you say shows that you believe that the class diagrams help explain the documents. I think that is wrong. They are part of the essential business model. Having the complete model, use cases and classes does help explain bad documentation, I agree. But producing proper documentation in the first place is quicker, simpler, less confusing etc.
Gil
PS On the previous reply, I didn’t tick the box that notifies me of followup comments by email. Can you help here please?
In a class diagram if a class doesn’t have any attributes which are relevant to a case study, is it permissible to have no attributes in a class, with only operations? Please answer
I still think these blogs are first class. I also still feel that you have to be careful providing full UML to the business. I constantly meet prohibitions against this; some people hate it.
Following this theme, I draw a ‘Domain Diagram’ as a ‘logical class diagram; in the entity modelling sense. The domain diagram only contains .’Business Objects’. which are classes that the CEO or lead business people will understand. Again, within a class, I may simplify the details, again to make it readable by the business; not just by Business Analysts, but by non technical managers and artisans. The Domain Diagram is drawn with one objective, and that is to encapsulate the Business Rules. There are 5 types of Business Rule:
1. Constraints on Classes
2. Constraints on Attributes
3. Pre-conditions on operations
4. Post-conditions on operations.
5. Constraints on the links between business objects.
I also draw use cases, but these more or less avoid the Business Rules. These describe what the user wants of the system, They are also restricted to simple concepts:
1. User (Actor)
2. Goal
3. Precondition
4. Trigger
5. Post Condition
6. Scenario (User-System interface – almost as a protocol – user does, system does.
Business Rules have a many to many association with most use cases, so sepparating them reduces many redundant use case steps. It also allows auto-matic testing, at two levels, so that when the use case is tested, it is known that the Business Rules already working.
Then analysis of the system falls down to two stages:
1. Have we covered everything that the user wnats to do (needs)
2. Have we covered all the business object contraints and rules the the Business requires, on top of the use cases.
For more detail, see my blog on the Wesite (blog) address attached. This shows how to use this approach in agile projects.
I got a question for you. Can javascript scenarios represented in UML. I know that javascript is a scripting language while JAVA being a pure object oriented language. But it is possible?
I think you can articulate the design of whatever you’re doing with some sort of UML. Class diagrams would help with describing the domain in which you are coding. State transition diagrams could be used if you’re coding anything stateful, etc.