This will be the second in a series of posts that will demonstrate simple use of the Unified Modeling Language in the context of a simple project. (Thanks to James Hudnall for the inspiration.) For the first installment, click here.

Objects and Classes

In our last installment, we identified and organized actors, the people and systems with which Your Comic Source will interact. Then I promised that in this installment, we'd identify and organize examples of our second UML concept: domain objects, the information and things that are of interest to the actors and that are affected by the things they do.

Now when I said "objects" above, some of you ran screaming from the room, thinking, "Oh, no, that means object-oriented programming! That's hard!" Well, personally, I think that "objects are hard" is very much old-school thinking. Literally old-school: the object-oriented (OO) approach is a hard transition for programmers who have mastered and adjusted to functional or structured programming. But in my experience, it's actually easier to teach new programmers using OO, because it's a more natural match to how we think and speak about the world.

And when I said "objects" above, others of you shook your heads in disapproval, thinking, "Oh, no, that means object-oriented programming! That means design and code. It's too early for that." There is a tendency to think:

objects = classes = code (Wrong!)

As I argue in my book and in my classes, objects are not just a code construct. Objects are everywhere, becuase they're just things and concepts in the world around us (and thus in the problem domain). Really, the proper formulation is simply this:

objects = nouns (Right!)

Objects are things. The actors and customers and end users are concerned about and work with things. Therefore, actors and customers and end users are concerned about and work with objects. And therefore, objects are an essential part of analysis, not just design and code.

But above, I also mentioned classes. "Aha!" cry the nitpickers. "Now classes are code! And it's too early for code. We told ya so!"

And again, I have to disagree. "Class" is really just another name for "category" or "kind" or "type" (though "type" also has code connotations). It just means a grouping of very similar objects that can be described in similar traits and terms. "Dog" is a class; Betsy, Bluebell, Jake, Radar, and Frosty are particular objects of the class Dog. They differ by many characteristics — breed, sex, height, weight, coat, color, age, and name being the main ones — but they're all Dogs just the same. Meanwhile, Gomer — who has a breed, a sex, a height, a weight, a coat, colors, an age, and a name — is fundametally not a Dog. He's of class Cat. We recognize Dog and Cat as different categories, even though it might be convenient to lump them together in the code.

So while it's true that OO programming languages have a concept called classes, it's not true that classes = code. Classes are a useful part of our analysis model, too. (Insisting that objects = code or classes = code is an example of the That’s Design, Not Analysis antipattern, as I discuss in Requirements Patterns and Antipatterns.)

But categories can themselves be grouped into categories. Or to speak in OO terms, a class can have a base class (or sometimes called a superclass, or a general class, or a parent class, or a number of different synonyms based on the speaker's programming language and habits) that describes common characteristics shared with other classes. For example, Dog and Cat have a base class of Mammal; and it's in Mammal that we describe the characteristics of breed, sex, height, weight, coat, color, age, and name. Because those characteristics are part of Mammal, they are implicitly part of Dog and Cat.

And just as a class can have a base class, it can have multiple subclasses (or sometimes called a derived classes, or a general class, or a child class, or other synonyms) that add more specific characteristics and details. The relationship between base class and subclass is sometimes called "inheritance", because the subclass inherits characteristics from the base class. The relationship is also sometimes called "specialization", because the subclass is a more specialized form of the base class. And in "official" UML parlance, the relationship is called "generalization", because the base class is a more general form of the subclass. (I really must apologize for all these different synonyms. They arose through different branches of OO evolution, and we're just kinda stuck with them. I'll try to consistently use "base class", "subclass", and "inheritance"; but I may slip up from time to time.)

I find that it's usually easier to analyze requirements in terms of classes of objects, not specific objects themselves. So even though I say we're going to identify domain objects, we're really going to look at domain classes more than objects. (I apologize if my terminology is confusing, but it's a habit I find hard to break.)

But what defines a class? Well, UML defines four basic parts to a class:

• Name. This part is obvious: what do we call the class (as distinct from individual objects of the class)?


• Attributes. What are the characteristics that describe objects of the class, and that may help us to distinguish one object from another? In our Dog example above, breed, sex, height, weight, coat, color, age, and name are all attributes.


• Operations. What are the things that all objects of the class can do? In our Dog example, all Dog objects can hunt and play and bark.


• Relations. How do individual objects relate to each other? How does the entire class relate to other objects and classes? A Dog object can have one or more Owner objects (and vice versa, trust me). Inheritance is an example of a relationship between two classes.

Brainstorming About Domain Objects

So now that we're all on the same page regarding domain objects, we can start identifying them. As with actors, if I'm completely new to a problem domain, I won't try to identify a lot of domain objects up front. Instead, I'll go straight to identifying use cases (the subject of our next installment), and then see if any domain objects are discovered through the use cases (as we'll see, possibly in installment 3, possibly installment 4 — I don't have a firm outline yet). I use the use cases partly as an exploratory mechanism, helpng me to explore and learn an unfamiliar domain. (I explain this approach in UML Applied.)

But when you know something about the problem domain, it may be easier to start by brainstorming and listing candidate domain actors. And as I explained in the last installment, I know a fair amount about comic stores! So I'm pretty comfortable in identifying and describing a lot of domain objects. As with the candidate actors from installment 1, this list won't be perfect: I'll miss a lot of domain objects, and I'll list some that we'll end up never needing. But this list is just a starting point for discussion.

So with a little thought, I came up with the domain objects shown in Figure 9:



Figure 9: YCS Domain Objects

The standard UML symbol for an actor is a three-compartment rectangle. The top compartment lists the name, the middle compartment lists the attributes, and the bottom compartment lists the operations. In Figure 9, I also drew some relations between classes, which I'll add to as my domain knowledge evolves.

Note that the domain objects in Figure 9 don't appear in any particular order, as should be expected from brainstorming. These domain objects are described below:

• Action Figure. A plastic, metal, or plush figure, usually of a character from some Comic Book or other Book. Often partly or fully articulated. (Don't ever call them "dolls" if you want to get out of the store without a lecture!)


• Board Game. A Game in which the rules and actions involve moving pieces or counters around a board.


• Book. A single volume publication consisting primarily of text, usually paperback or hardbound.


• CCG. a.k.a. Collectible Card Game.


• Comic Book. A single volume publication consisting primarily of fully illustrated stories (with text as only a secondary element), usually bound in glossy paper or card stock. A single Comic Book may tell all or part of a story.


• Comic Series. A continuing, regularly published series of Comic Books (i.e., numbered "Issues") that involve a common theme, common characters, or common creators.


• Customer. A person who buys Comic Books, Books, Games, or other merchandise at the store. (See below for more discussion of Customer.)


• Customer Order. An Order placed by a Customer to purchase various merchandise.


• Distributor. In most cases, comic stores do not deal directly with individual vendors. Instead, they work Distributors who research and buy from vendors and then solicit orders from the stores.


• Distributor Order. A merchandise order that the store places with the Distributor.


• Employee. This object represents the information that is known about a particular Employee. (See below for more discussion of Employee.)


• Game. A product which allows one or more players to compete against each other or against a set of challenges, all according to a set of rules.


• Game Calendar. A calendar of upcoming Game Events.


• Game Event. A scheduled playing session at which one or more players will play one or more Games.


• Graphic Novel. A single volume publication consisting primarily of fully illustrated stories (with text as only a secondary element), usually bound in hard back or heavy card stock. A single Graphic Novel usually tells one complete story, and usually contains more pages on higher quality paper stock than a typical Comic Book.


• Magazine. A single volume publication consisting primarily of ads, illustrations, stories, articles, and editorials, all of which involve a common theme, common topics, or common creators. Most Magazines are periodicals (with a regular publication schedule), but some are special editions. A magazine is usually bound in and printed on glossy paper.


• Payable Account. An account of funds that the store owes (usually to a vendor, a Distributor, or an Employee).


• Receivable Account. An account of funds that the are owed to the store (usually by a Customer).


• Release Calendar. The schedule of when particular merchandise is expected to arrive in the store.


• RPG. a.k.a. Role Playing Game. A Game in which the rules and actions involve players telling an interactive story in a setting and plot devised by a gamemaster.


• Subscription. A request by a Customer to purchase in advance every issue of a Comic Series or a Magazine.


• Supplement. A Game that does not stand on its own, but rather adds additional rules and options to some other Game.


• Supplies. Merchandise such as counters, dice, comic bags, and other materials which may be used with a Game or Comic Book or other merchandise, but which would usually not be of interest to anyone who hadn't purchased said merchandise (i.e., most people have no use for comic bags unless they buy Comic Books to put in them).


• Time Sheet. A record of the hours an Employee worked.


• Trade Paperback. A single volume publication that collects a number of issues of a Comic Book, usually bound in hard back or heavy card stock. The material contained is not original, but a Trade Paperback is otherwise very much like a Graphic Novel. A single Trade Paperback usually tells one complete story, and usually contains more pages on higher quality paper stock than a typical Comic Book.


• Video Game. A game played by one or more players on a computer or a game console.


• Work Calendar. A schedule of hours to be worked by various Employees.

Note that two of these classes, Customer and Employee, have the same namea as actors from Installment 1. These objects represent the information we know about those actors, not the actors themselves. You may find it confusing that the actors and the classes have the same names. I do, too, honestly, so my usual practice would be to call these "records": Customer Record and Employee Record. But to some people, record = database = design, and they jump back to the That’s Design, Not Analysis antipattern. So when I think that might disturb them, I avoid the phrase "record". In retrospect, I'm feeling that the name confusion is every bit as bad as That’s Design, Not Analysis; so maybe a better choice would be Customer Info and Employee Info. "Info" is such a nice, vague word that no one can really mistake it for a design decision. So I'll switch to those terms as we move forward.

Relating and Organiing Domain Objects

To repeat: the domain objects in Figure 9 appear in a scattershot stream-of-consciousness order, with little thought about how particular domain objects might relate to each other. And just as with the actors in Installment 1, it will be useful to organize the domain objects into packages and also to expand upon the relations between them. So I'll start by subdividing the domain objects into the packages shown in Figure 10:


Figure 10: YCS Domain Object Packages

Accounting Objects

We'll look at each of these packages in more detail below, starting with the easiest: Accounting. This package's contents are shown in Figure 11:


Figure 11: YCS Accounting Objects

In this diagram, I added a new class, Account, to represent characteristics and behavior that are common to both Payable Accounts and Receivable Accounts. I also added two classes found in the Parties package but related to classes in this package: Employee Info and Party (discussed under the Parties package below). I drew these two classes in dark red to make them stand out, as a way to indicate that they're external to this package.

There are two kinds of relationship shown in Figure 11:

• Generalization. As above. Shown with a triangle-headed arrow.


• Association. Shown with a line or arrow, this relationship between two classes indicates that the classes collaborate in some way. You should prefer a line when the two classes interact freely. You should prefer an arrow when one class controls or "owns" the interactions. In Figure 11, for example, there are navigable association from Payables Account and Receivables Account to Party, indicating that the accounts are Paid To or Owed By particular Parties. There is also a simple association between Time Sheet and Employee Info.

(Other types of relations are possible, as we'll see in future installments of Everyday UML.)

Note also that I added specific attributes and operations to some of the classes: an Account has a Balance, and you can Deposit or Withdraw funds (in specific Amounts) or transfer them to another Account; and a Time Sheet indicates the Hours Worked. But I didn't add any attributes or operations to the other classes. In part, this represents that I simply haven't thought through those other classes yet. But it also reflects an important UML practice: not every detail you know appears in every diagram. I called this The Model Rule in UML Applied:

We saw The Model Rule in chapter 1; but it bears repeating. To use UML effectively, you should never be simply drawing pretty pictures; you should always be editing an underlying model, using the pretty pictures as your user interface. Thus, the model should contain more information than is displayed in any one diagram; and information in one diagram should not explicitly contradict information in another diagram. Information that is found in one diagram but not in another should not be considered a contradiction. Rather, this simply indicates that the former diagram displays more detail than the latter. Details may be omitted from a given diagram to make it more comprehensible.

But how do you keep these diagrams consistent with each other? How do you maintain the underlying model? This is where a good modeling tool proves its worth: a good modeling tool will maintain the model as you create and edit your diagrams. If you are not using some sort of modeling tool, this very mechanical burden will fall on you, rather than on the machine. That’s a poor division of labor: brains should do brain work and machines should do mechanical work. If you do the mechanical work, you will do it imprecisely and inefficiently, and you’ll have no time for brain work.

Note the plus sign (+) in front of the attributes and operations in Figure 11. This indicates visibility, a concept which has a lot of design and code implications, but can be summarized pretty simply: the visibility of an attribute or operation indicates where it can be seen and used. Public visibility (+) means an attribute can be read and changed by any part of the system, or an operation can be requested by any part of the system. Private visibility (-) means an attribute can only be read and changed by the class that defines it, or an operation can be requested by the class that defines it. And protected visibility (#) is like private, but the attribute or operation is also visible to all subclasses of the class that defines it. For analysis work, public visibility is the most common, and you shouldn't worry too much about visibility concerns.

Calendar Objects

The contents of the Calendars package are shown in Figure 12:


Figure 12: YCS Calendar Objects

As in Figure 11, Figure 12 indicates an external class (Game) in dark red. I also added attributes to the Game Event class, and I indicated that a Game Calendar contains zero to many (0..*, in UML notation) Game Events.

But the largest addition in Figure 12 is the two added base classes: Schedule and Chronology. These are based on the Chronologies pattern from Requirements Patterns and Antipatterns. Here's a brief excerpt:

Start with an Event class. It should have attributes that describe an event, and that distinguish one event from other similar events. Some of these attributes might include a name, a description, and start and end times for the event. You might also want to indicate whether the event is recurrent (and if so, on what interval) and also whether the event has been completed or not. And you may want your Events to be able to issue notices when they’re due. Event may also be a base class, from which you derive more specific event types. And Event objects may relate to other Event objects. For example, an appointment Event might involve one or more reminder events that remind the user that the appointment will soon occur.

Next, add a class, Chronology, that represents a list of events. It should include operations to add and remove Events. This general class contains Events both past and future. You may also want to add specific Schedule and History subclasses to represent future and past event lists. If you want to maintain both historical and planned events, then your Schedule class should include an operation to complete an Event and move it into a specific History.

Given that excerpt, it makes sense to add an Event base class, modifying Figure 12 to look like Figure 13:


Figure 13: YCS Calendar Objects (Revised)

The change from Figure 12 to Figure 13 is an example of applying a pattern. Again, from Requirements Patterns and Antipatterns:

So putting the two definitions [of "pattern"] together, we see that patterns are a little bit of art and a little bit of science. The science part comes in as three tasks:

• Discovery. Finding some best practice, and recognizing that it is common enough to be worthy of documenting as a pattern.


• Cataloguing. Documenting a number of patterns in detail, including how to recognize them, how to apply them, and even when not to apply them.


• Study. Learning to recognize the patterns, and understanding them well enough that they become part of your nomenclature.

Then the art part comes in when you apply the patterns. You have to learn how to speak in terms of the patterns, how to see where they fit, and how to apply them. It takes a good eye to see the opportunities that patterns create for you; but when you do, they will save you a lot of effort, because they will give you a lot of basic, common, starting ideas without you having to invent those ideas yourself. That will leave your brain free to focus on the aspects that are unique to your problem and your team.

I like to tell students that good patterns let them walk into a new project with some great ideas "in their back pockets", ready to pull out as soon as they see a need. You can apply a lot of established wisdom by building on patterns (where appropriate). We'll see more pattern usage ahead, in both this and future installments.

Party Objects

The contents of the Parties package are shown in Figure 14:


Figure 14: YCS Party Objects

In this package, we see more detail on the Party class that was introduced in Figure 11. This is based on the Party pattern from Martin Fowler, as described in Analysis Patterns : Reusable Object Models. This is a pattern that abstracts out the common characteristics or people and organizations into a base class, Party. A Person, then, is a subclass of Party that represents an individual; and an Organization is a subclass of Party that represents a group of Parties. Person and Organization then serve as base classes for our existing classes: Employee Info, Customer Info, and Distributor Info.

Besides the Party pattern, Figure 14 is also based on the Contact Info minipattern from Requirements Patterns and Antipatterns, in which a single Party can have multiple types of Contact Info, a base class with subclasses that represent different ways a Party might be contacted.

Order Objects

The contents of the Orders package are shown in Figure 15:


Figure 15: YCS Order Objects

I added the base class, Order, as well as a Line Item class to represent items in an order. The Order is placed by a particular Party. (The upper part of the diagram is a simplification of the Orders pattern from Requirements Patterns and Antipatterns.)

I also changed Subscription to be a subclass of Customer Order, one which references a particular Periodical to which the customer subscribes. (The Periodical class is described below.)

Merchandise Objects

The top-level of the Merchandise package are shown in Figure 16:


Figure 16: YCS Merchandise Objects

I added a base class, Merchandise, to represent things sold at YCS. I also added a subclass, Publication, to represent printed Merchandise.

Game Objects

The contents of the Games package are shown in Figure 17:


Figure 17: YCS Game Objects

Publication Objects

The contents of the Publications package are shown in Figure 18:


Figure 18: YCS Publication Objects

I added a Periodical class to represent a scheduled release of issues of some Publication. A Comic Series, then, is a subclass of Periodical; but after a little thought, I decided that a Magazine is also a subclass of Periodical, and it is individual Magazine Issues (a new class) that are published on the schedule.

Note also that I show a new UML relation in Figure 18: dependence, shown as a dashed arrow. While an association (either navigable or not) indicates some structural or functional connection between two classes, dependence indicates a simple "awareness" from one class to another. In Figure 18, we have an association from Periodical to Publication, indicating that a Periodical will consist of some number of Publications. So it would be redundant and even possibly confusing to also have an association from Comic Series to Comic Book, or from Magazine to Magazine Issue. Instead, I redrew those relations as dependence, indicating that a Comic Series "knows about" the Comic Books that make it up, and a Magazine "knows about" its individual issues. (We'll see more about dependence in future installments of Everyday UML.)

Other Merchandise Objects

Although this won't add much of interest, the contents of the Other Merchandise package are shown in Figure 19 for the sake of completeness:


Figure 19: YCS Other Merchandise Objects

What's Next?

In my next installment of Everyday UML, we'll finally get to some use cases. I can't give a schedule for that, so keep your eyes open!

ZDNet Australia posts this essay on requirements from Psychologist Craig Errey, managing director of PTG Global. The essay is brief, and thus just barely introduces the complexities of requirements analysis; but I recommend every word of it. Particularly these words:

The user interface should no longer be considered a non-functional requirement. The user interface requirements should be given the same standing as functional requirements and conducted in parallel.

There's a strong belief in software that the user interface is not a user requirement, but rather a design/implementation artifact; and I'm happy to see Mr. Errey fighting against this approach. The end users have expectations and requirements when it comes to the user interface. To them, it is a near-tangible thing, right up there with schedules and reports and orders and other domain objects. As I write in my forthcoming Requirements Patterns and Antipatterns:

The customers and end users may expect (and thus require) certain designs. In particular, since the user interface is most of what they understand of the system (see the discussion of the Iceberg Secret under the Prototyping pattern), they may have strong opinions and expectations regarding a particular user interface design. And as we discussed in chapter 1: if the customer expects it, it’s a requirement.

(And for those who recognize the Iceberg Secret in that excerpt: yes, I give full credit for the metaphor to Joel Spolsky, and encourage people to read his essay in its entirety, as well as his whole book. I'm a big Joel fan, even when I think he's wrong.)

An arbitrary line that says the user interface is not a subject for requirements analysis can even be seen as a form of Geek Speak.

The first in a series of excerpts from my next book. This antipattern was mentioned in Everyday UML, Installment 1: Identifying and Organizing Actors.

Anecdote: Programmers Are Weird!

Symptoms: Customers who get frustrated talking to developers who are working as analysts. The jargon and abstraction overwhelms them.

Context: Projects where programmers act as analysts (i.e., programmer-analysts) yet lack training or experience in customer communications. Usually not projects where the customers are also technical personnel.

Motivations:

• Programmers like technology, like to talk about it, and spend much of their time immersed in it. It forms a comfortable language for them, including standards and conventions that simplify and clarify communication.


• 
  
  
  
  

  Programmers further develop writing habits (i.e., coding standards) that help produce more readable and maintainable code. They internalize these habits and tend to use them across the span of development activities. Yet despite programmers’ “comfort level” with these habits, the habits can be completely confusing to regular people.

  Programmers develop writing habits that help produce more readable and maintainable code, but can be completely confusing to regular people.

  
  


• Programmers also like to work in the realm of abstractions: ideal cases and especially common cases that allow programmers to create a solution once and then apply it (with necessary modifications) across a wide range of cases.


• 
  
  
  
  

  Customers and end users tend to work in the world of the concrete: real, distinctive jobs to be done for real, distinctive clients – and with real, distinctive problems and complications and consequences that popup. While they may think about abstract general principles when they need to, their work biases them toward the concrete. Most end users don’t deal with abstractions to the degree that programmers do.

  While customers may think about abstract general principles when they need to, their work biases them toward the concrete.

  
  


• For various reasons – cost, trying to facilitate communication, and simply not knowing any better being chief among them – many development organizations have programmers serving as programmer-analysts, but without training as suggested under the Trained Analysts pattern.

Problem: The problem, I hope, is obvious: programmer jargon can confuse customers and end users. That’s not news to anyone, and it’s a major consideration in many of the patterns in this book. But I want to draw particular attention to two common but confusing programmer habits: coding standards and abstractions.

Programming standards lead programmers to write (and sometimes talk) in odd-but-precise ways that have specific meanings to computers. And beyond that, we (I can be as guilty as anyone) like to show how clever we are by using these odd formulations in non-technical settings. It becomes a form of in-joke: “Let me just access the ICashMachine interface over here so I can instantiate some cash objects.” Our fellow programmers get the joke, laugh, and probably then try to top us. And if regular people took at us funny, shake their heads, and mutter “Geeks,” we take it as a badge of honor. They don’t get the joke, but we do.

And those odd formations really do serve a useful purpose in code; but boy, do they look odd! We stick an “I” in front of anything we “talk” to: IAccount, IBankSystem , ILeasingCompany. And as the examples above show, we like to jam together longStringsOfWordsThatNameSomething, and to use funny capitalization when we do so. And we like to use odd punctuation combinations, such as “==”. “::”, “->”, and “///”.

And believe it or not, every one of those odd usages has a specific and useful meaning. I could teach it to you, even if you’re not a programmer. As a customer, you could learn how to understand it. But why should you have to? Those odd usages are designed to help us to talk to computers, not to people. Just because we geeks can understand them doesn’t mean those habits belong in a requirements discussion. And yet they often end up there. Even when they’re being serious, programmer-analysts who write documents and especially programmer-analysts who create models tend to sprinkle them liberally with coding standards, with their vision of how the code might look. That makes it harder for customers and end users to understand those documents. Since the audience for those documents is people, not computers, that’s just not a smart idea, no matter how compelling it seems to the programmers.

Customers could learn how to understand the arcane jargon of programmers. But why should they have to?

Abstraction is a more insidious problem, because it has some real benefits during analysis as well as some real drawbacks. It’s important for analysts (including programmer-analysts) to identify general principles, commonalities, and other abstractions that can aid their understanding of the problem domain. But it’s also important to realize that customers and end users may not think in those abstractions; and trying to force them to do so may actually hinder communication. It’s all right to introduce an abstraction into the conversation and see if it helps; but you have to be ready to fall back on the concrete if the abstract doesn’t work.

There’s another potential problem with abstractions during analysis: they’re often a sign that you’re designing, not analyzing. When programmer-analysts start seeing possible solution abstractions, they may introduce those into the requirements documents. Not only can this confuse customers and end users, but it can also lead stakeholders to assume that these design concepts are actually requirements (as discussed under the That’s Design, Not Analysis antipattern).

Solution Name: Speak English!

Solution: Fortunately, this is usually a self-correcting problem. Just remind programmer-analysts to rewrite their text or models and to revise their remarks to aim for a general audience. That should be enough to get them to correct themselves.

Remind programmer-analysts to rewrite their text or models and to revise their remarks to aim for a general audience.

In particular, ask programmer-analysts to strip out coding standards wherever they appear, unless the requirement they’re documenting is actually a coding requirement (such as a required interface or protocol or algorithm). And if they’re using abstractions that seem too far from your problem domain for you to understand, ask them to go back to specifics first. From there, ask them to talk you through to explain the benefits and purpose of the abstraction, including how they expect the abstraction will apply across a wide range of cases. And if they can’t do that, then explain to them that the abstraction may be useful as a design concept – and should be documented in their design notes – but is complicating matters when it comes to requirements.

Resulting Context: With a few reminders from customers and end users (and a few jokes at their expense, as needed), programmer-analysts should learn to communicate with a general audience.

Discussion: This antipattern can be a special case of another antipattern: The Department of Obfuscatory Verbiage. And the solution relies heavily on The Echo Effect: stakeholders have to let programmer-analysts know when they have failed to communicate. And the ultimate solution, of course, is Trained Analysts, whether they’re programmers by title or not.

This will be the first in a series of posts that will demonstrate simple use of the Unified Modeling Language in the context of a simple project. (Thanks to James Hudnall for the inspiration.)

What the Heck is UML?

For those who are new to the Unified Modeling Language (or UML), here's a very brief introduction. UML is essentially a set of blueprinting notations for various aspects of system design, with an emphasis on communication to customers, end users, and other developers. Sadly, a lot of software isn’t really designed in the traditional sense. If I gave you a pile of nails and lumber, I’ll bet you could build a decent doghouse by eye. You might build a decent house, but you’d probably want to draw a sketch, at least; and I’ll bet you’d never pass inspection without that sketch, whether you needed it or not. And if you tried to build a skyscraper without detailed plans, you’d never get it off the ground without it collapsing; and government types would shut you down before somebody got hurt. (Thanks to Steve McConnell for the analogy.)

Well, a lot of software is built with doghouse methods, even if it’s a skyscraper project. UML is an industry-standard set of diagram types and modeling syntax that help you draw the plans. It's a standard maintained by the Object Management Group. It won't solve all your problems, but it's a useful tool to help you progress from doghouses to skyscrapers.

Defining the Model

Before you begin modeling, it's always a good idea to identify the purpose of the model. That will help you to know the scope of your model and to thus limit and focus your work.

For this stage of Everyday UML, our model will be defined as follows:

This is a model of operations for Your Comic Source, a full-service comic and game store with both storefront and online sales and events.

Note that this model is described as a model of operations for the comic store. That implies that this is a business model, focused on the operations of the business as a whole, not just on the operations of the software. Remember my message from UML Applied and UML BootCamp:

UML is not about software design; it's about system design, where a system is structure with behavior and goals. And software is certainly one kind of system, but it's not the only kind.

And in this particular set of examples, the system will be the entirety of Your Comic Source.

A business model is only one kind of model you might construct with UML. We'll see other kinds of models in future installments of Everyday UML.

Brainstorming About Actors

It's time to introduce our first UML concept: actors. No, we're not talking John Cusack or Marisa Tomei here. In UML, an actor represents a person or system or event with which your system interacts. It's the things outside your system that either ask your system to do things, or that do things for your system, or both.

If I'm completely new to a problem domain, I'll start with a single actor, Customer, use that as a probe for finding use cases and then participating actors, and then use those actors to probe for more use cases and more participating actors, and so on. (I explain this approach in UML Applied.) But when you know something about the problem domain, it may be easier to start by brainstorming and listing candidate actors. This list won't be perfect: you'll miss some actors, and you'll list some that you'll end up never needing. But remember another lesson from UML Applied:

Don’t worry about being perfect all at once (or ever!). If you’re communicating, you’re using UML effectively. There’s always room for improvement; but don’t let imperfection stop you from progress. That’s a key point in learning UML and in applying UML as part of a process. Your designs will not be perfect; but as your team reviews them and you refine them, they will become good enough: good enough to build the system, good enough to guide the testing and the documentation, good enough to drive the management of the process. A team that waits for perfection is just as bad as a team that is wedded to code-and-fix: neither team produces an effective design that leads to a successful system. Remember: code-and-fix bad; design-and-fix good.

One look at my bookshelves should serve as proof that I've spent a lot of time in comic stores. So I felt pretty comfortable in modeling actors for Your Comic Source (a.k.a. YCS) as shown in Figure 1:




Figure 1: YCS Actors


The standard UML symbol for an actor is a stick figure (whether the actor represents a person or not.) Note that these actors don't appear in any particular order, as should be expected from brainstorming. These actors are described below:

• Bank System. A computer system at the bank. The YCS system will collaborate with this system for payments and other transactions.
  
• Browser. Someone who visits the YCS Web site but who isn't yet a Member.
  
• Customer. Someone who purchases comics or games at YCS, either in person or online.
  
• Gamemaster. This is a person who arranges and runs game events for Gamers.
  
• Gamer. A person who plays games at the YCS store. (Games stores often have space for regularly scheduled games, as a way to expand interest in those games and sell more products.)
  
• Manager. The person in charge of day-to-day operations at YCS.
  
• Member. This is a Web site visitor who has moved beyond Browser status by creating an account and identifying interests. When comics or games of interest to that Member are released, YCS will send out email notices. Members will also qualify for special discounts and deals.
  
• Publisher. A person or company who publishes comics for sale at YCS.
  
• Special Guest. An artist, writer, game designer, publisher, or other individual who will visit YCS for a special event such as a book signing or a talk.
  
• Staffer. Someone who works the shelves or the counter at YCS.
  
• Store Owner. The owner of YCS.
  
• Subscriber. Someone who signs up for and purchases particular comic books in advance, and whose books are then delivered automatically (either in person or via delivery service).
  
• Vendor. This actor represents a person or company that sells or distibutes or consigns products for sale by YCS. (Definitions: Sells = "YCS purchases the item directly. All future profits or losses accrue solely to YCS." Distributes = "YCS stocks the item, but does not purchase it. Upon sale, proceeds are split between distributer and YCS. After a period of time, YCS may return unsold items." Consigns = "Similar to distribution, but a one-time arrangement between YCS and a private individual.")
  
• Vendor System. A computer system owned or run by a Vendor. It will work with the YCS system to transact business.
  

Remember a key rule in regard to actors: an actor represents a role that individuals or systems may play, not any specific individual and not any specific job title. One person or system may fill multiple different actor roles at different times, and a single actor role may be filled by different people or systems at different times. For example, the owner of YCS may fill the Store Owner role primarily, but may also act as a Manager or even a Staffer from time to time.

Relating Actors

To repeat: the actors in Figure 1 appear in a scattershot stream-of-consciousness order, with no real thought about how particular actors might relate to each other. But actually, there's a lot of things we know about these actors already. Next we want to capture that knowledge. Some of these things are shown in Figure 2:



Figure s: YCS Actors (Reorganized)


There are two kinds of relationship shown here:

• Generalization. Sometimes also called specialization, inheritance, or subclassing. Shown with a triangle-headed arrow, this relationship between two actors indicates that one actor is a special case or special kind of another actor (the one to which the arrow points). For instance, Figure 2 says that a Publisher is a special kind of Vendor.
  
• Association. Shown with a line or arrow, this relationship between two actors indicates that the actors collaborate in some way. You should prefer a line when the two actors interact freely. You should prefer an arrow when one actor controls or "owns" the interactions. (We call this a "navigable association", perhaps because the UML standards committee is fond of multisyllables). In Figure 2, for example, there is a navigable association from Manager to Employee, indicating that a Manager has Employees that work for him or her. Note also that the association includes a measure of multiplicity on the Employee end (where it reads "0..*"). Multiplicity indicates how many actors of a given type are involved in the relationship. "*" indicates an unspecified number; so 0..* in our example means that a Manager might have any number of Employees (including 0 — maybe they all got fired?).
  

(Other types of relations are possible, as we'll see in future installments of Everyday UML.)

Note also that I added some new actors into Figure 2. These actors represent common behavior shared by a number of different actors, and let us describe the common behavior in a common way. This is an abstraction, and can be useful. But you have to be careful: too much abstraction too early can confuse your audience. (For more on this topic, see item 64: Geek Speak from my upcoming book, Requirements Patterns and Antipatterns: Best (and Worst) Practices for Defining Your Requirements, coming soon from Addison-Wesley.) These additional actors are:

• User. This actor represents behavior common to all users of the YCS Web site. (This is a simplified version of item 56: Extended Inverted Org Chart from Requirements Patterns and Antipatterns.)
  
• Authorized User. This actor represents users who have some level of privileges within the YCS Web site, such as editing their personal preferences, etc. (This is another element of Extended Inverted Org Chart.)
  
• Employee. This actor represents common behavior for all persons employed by YCS. (This is a simplified version of item 55: Inverted Org Chart from Requirements Patterns and Antipatterns.)
  

Organizing Actors

Notice how I drew lines around groups of actors in Figure 2, dividing them into groups by relations. That suggests better ways to organize the actors. But to organize them, I first need to introduce UML packages. A Package is simply a hierarchical subdivision of a model. It functions very much like a folder on your hard drive, letting you organize a large collection of things into smaller, more comprehensible collections of related things. The icon for a UML package even looks like a file folder, just like a folder on your hard drive.

Looking at Figure 2, it seems natural to me that we should organize the actors into the packages shown in Figure 3:




Figure 3: YCS Actor Packages


This is a stripped down version of item 48: Actor Hierarchy from Requirements Patterns and Antipatterns. The Human Actors package is split into two subpackages, as in Figure 4:




Figure 4: YCS Human Actors


The Users package models the various kinds of users, as in Figure 5:




Figure 5: YCS Users


The Customers package models the various kinds of customers, as in Figure 6:




Figure 6: YCS Customers


And finally, the Systems package shows systems with which YCS must interact, as in Figure 7:




Figure 7: Systems that Collaborate with YCS

Organizing Your Model

Well, that's enough about actors for now. This installment is already a lot longer than I intended. But there's one more topic I want to cover: where these actors fit in the larger model that we're creating. There are a lot of ways that you can organize a model. I like to use an organization scheme as shown in Figure 8:




Figure 8: Organizing Your Requirements


The Actors package contains all the work we've seen in this installment. The Domain Objects package will contain details on things and types of things of interest to the actors of YCS. The Use Cases package will show Use Cases: the operations that actors perform within YCS, including the business rules that apply to those operations. And the Architecture package will show software systems and interfaces that will support the use cases.

What's Next?

In my next installment of Everyday UML, we'll look at some domain objects. I can't give a schedule for that, so keep your eyes open!