Tuesday, December 15, 2009

Design Before You Develop - Intro to Class Diagrams with Quick Reference

If you already are a design-before-you-develop junkie like I am, daps to you. You can probably stop reading here and move onto the next blog in your queue. For the rest that are curious about it but don't know where to start, read on.  It's my opinion that you should get into the good habit of designing before you develop. Even if the design takes you 10 minutes on a scratch pad, a quick design session on a whiteboard or several days in a full blown modeling tool, you should do it.

Why? Because it's during those sessions that you and your team can express the intended inner workings of your software modules, poke holes in it, rinse then repeat as needed. You can focus on a list business of requirements, design the class diagrams and literally step through the requirements allowing you to articulate the path of execution that'll take place to fulfill each requirement. All of this is done without a lick of code. You discover design flaws early on, not during development. That's risky. You can even take it a step further and generate sequence diagrams against your UML model and requirements, they are invaluable! But sequence diagrams are outside the scope of this article, we'll get to it some other time.

I'll say it again and again that during the design process you need to forget the code. Coding should be the easy part. It's the design that lends your software scalability and flexibility. Without a proper design, you run the risk of causing not only future headaches for yourself and your team but more importantly, the business. Yea yea, without the design phase it's so much faster to release a product. Sure, you can tell your boss/client what you're doing is rapid development. Sure, your bosses will be happy for the time being cause you got it out so quick. You're the hero. You're the man. But who cares if you are spending the next year after your go live fixing code, trying to re-design after the fact and burning through company cash hand over fist. Or worse, bandaiding already production level code with cut rate code because everything is an "emergency" and you don't have the luxury of thinking things through anymore. All the while the boss that was singing your praises is no longer impressed that you put out a piece of software that constantly breaks. It's a vicious cycle and could've been avoided by dedicating a little more time to designing up front. Use the above as a case to your boss when you need a little more leeway to get some design cycles in in the beginning. Just like Ben Franklin put it:
An ounce of prevention is worth a pound of cure.
He was a pretty smart dude, and his quote certainly applies to software engineering. Let's put in that ounce of prevention by designing first eh?

UML to the beginner can seem pretty damn intimidating. In my comp sci class I remember cracking open the UML section and my eyes glazed over at all the fricking symbols. I thought to myself, how in the hell am I going to memorize all this? After I got some real world experience, it's really not that bad. Given, you can get pretty deep into it I find that I'm able to express a software model with only a few symbols. I thought I'd share with you some of the ones that I use all the time with Microsoft Visio however the symbols below are not application specific, they are universal symbols. Here's the quick reference:

These symbols should be more than enough to get you going. Below is a what a real class diagram might look like using all above symbols:

In the above class diagram, there are two applications being modeled at the same time that use shared components. A school app and a war game app. I've put together some questions I'd ask myself while making some observations of this class diagram:
  • Person is being extended by Student and Soldier. 
  • Soldier is in the common package. "Is this correct? Shouldn't it be in the wargame package? What happens if its not?" 
  • Soldier can have many pistols. "But is that true? Should it be a one to one? Should there be a collection manager of sorts to keep the api simple? Better ask the business."
  • Student can have many books via its multiplicity. "Same multiplicity questions apply here?"
  • Student is teachable, since it implements ITeachable. "Are the methods defined here really granular? Do they really belong in this interface? Is there anything else I can add to this interface?"
  • A pistol implements IWeapon so it must fire.
  • fire() on the IWeapon interface returns numeric. "Is this the proper return type?", "Should it be another return type?", "Are we going to calculate fire() based on the numeric damage its dealt?,  If so keep it. If not, let's redesign".
  • Soldier doesn't have an interface. "Does Soldier need an interface?", "Is there something that all soldiers must be able to do? Let me dig into the requirements and do some textual analysis."
  • Person has a firstName, lastName and age member. "Are these shared across all Person objects?". "Do they need to be specific to a subclass?"
  • All classes are have their packages before the name so it's clear where each class should exist.
This list could go on and on!

All of these questions should be addressed during design to ensure you and your team have a clear path of development. There are a bunch of open source tools out there especially in C# built into Visual Studio (and I'm sure Java has theirs too) that will parse through class files to generate UML diagrams ad hoc. For ColdFusion developers, at the time of this entry, Mark Mandel has been recently tweeting about a prototype he's working on that will generate UML using ColdDoc and UML2 tools. Initial screen caps looks promising, so it's definitely something look out for. For more info check out Mark's twitter.

I'll also add that it's important to note that these tools should not be misused. Meaning you shouldn't develop first just to produce a class diagram against off-the-cuff code. These tools should be used when you need a way to dynamically create accurate class diagrams from current code for a number of reasons:

  1. You may be working within an enterprise level organization where there are multiple teams with their own special access to certain aspects of the code. Developers often need to know how to leverage an API in which they have no access to the source. In my experience that's where these automated UML tools come in handy. You can print it out and ship it off to whatever team needs it. From the UML, they can discern the contracts in which they need to develop against.
  2. You don't have to deal with the headache of documentation maintenance.
  3. You need to reverse engineer and analyze design at a high level, especially if the code base is pretty huge and there's a lot going on.

So that's class diagrams in a nutshell and hopefully you'll give the design before you develop approach a try if you haven't already. It may seem like a long and drawn out process at first but believe me practice makes perfect. Take it little by little. Maybe try it with that new module that needs developing or that module that is in need of some major refactoring that you've been putting off for months. After awhile, you'll be zipping through design sessions quickly because you've trained yourself to identify patterns and problems during that analysis phase. It'll eventually become second nature and you'll soon feel dirty not doing some form of design up front.

Hope this helps.


Beginning C# Objects: From Concepts to CodeHIGHLY recommend this book for the beginner UML/OO developer. C# is in the title but the content applies to all languages.

No comments: