Speak to Me, UML!

I don't know about you, but when I first learned about UML, I was ecstatic! I was just so excited to have a standard way to represent my object model in class diagrams in ways that were easy to sketch and understandable by others. I created diagrams every chance I got.

Here's an example of what my class diagrams looked like back then:

Yep, that's what they looked like, except with about three or four times the number of classes as we see here. Sure, they were factually correct, but they were also so doggone verbose that they were only good for stuff like auto-generating stubbed out classes.

Reading a diagram like that is a bit like reading an almanac. Don't get me wrong -- sometimes you need an almanac. But most of the time, a diagram like that isn't speaking to me about anything in particular. It's just plopping tons of information on my lap. That's totally TMI.

Leave it out! It's all right.

You know what? It's actually entirely acceptable to elide details from your diagrams. Ambiguity is a-okay. For example:

1. A line between two classes indicates some kind of association between them but without arrowheads, it doesn't specify the nature of that association. Who depends on whom? Is it aggregation? Composition? We don't know.
2. If you omit an attribute or operation, it doesn't mean that it doesn't exist. It just means that it's not on the diagram. You don't have to include toString() on each class unless that's important to what you're trying to convey.
3. In fact, if you only need to convey class relationships, you can omit the attributes and operations entirely.

Owners Manual or Repair Manual?

One way that eliding can be helpful is when you're working on documentation for consumers of your code. For example, when I purchased a microwave, the manufacturer included an operator's manual, but thankfully did not include a technician's microwave repair manual. When I'm trying to look up how to change the power level on the microwave, I don't want to have to sift through information about how to service the capacitors, magnetrons, or transformers.

Actually, I don't even know what magnetrons or transformers are... but I do know that Magnetron would be an awesome name for a Transformer. He sounds like he'd be a Decepticon, though. Definitely a Decepticon.

Anyway, same thing about the owner's manual goes for writing documentation for your consumers -- just show what's relevant. Let your UML say something – by not making it say everything. Instead, your diagram could look something like this:

That's a whole lot easier to digest. It more clearly speaks to me about the components involved in authentication.

So, free yourself of the burden of including every minutia of your entire application's object graph! Instead, consider your audience, and add only the level of detail that's required.

By omitting the extraneous, you'll amplify the important!