Software Modeling: Why Bother?

If you've written software for any length of time professionally, or even if you're in school, you have likely come across at least one UML diagram. If not, let's have a quick refresher (or introduction for those under the proverbial rock).

UML is a formal language created to model different aspects of software construction, user interactions with software, activities that code and/or users carry out, and more. The standard UML diagrams are Class, Sequence, Activity, and Use Case diagrams. A quick description of each is below:

• Class diagrams - these diagrams are used to present visual models of software classes, and are generally used for languages with some measure of classic OO like C++, C#, Java and others.
• Sequence diagrams - a sequence diagram is a high-level diagram used to visually depict the sequence of events for a given software module, IPC/RPC call, a user-initiated event in a software system, and just about anything that contains a sequence of events that can be illustrated (even washing clothes, which I can graph easily but I try to avoid in real life).
• Activity diagrams - activity diagrams are used to illustrate a specific activity. This is another high-level diagram that depicts sequences of events, except that an activity diagram is more thorough in illustrating how those sequences are carried out.
• Use Case diagrams - use case diagrams are used to visually illustrate what a given item will be used for. This is usually used to depict use cases for a screen in an application, a software module, or anything that has uses and is useful (like a washing machine).

In case you haven't noticed, UML diagrams are used to visually convey information. That means the consumer of a UML diagram should be able to visually grasp the information being conveyed. If this is not possible, the diagram isn't useful, and in practice, this happens all too often (like when a class diagram has a few hundred classes). What this means is there are some good guidelines on what should go into a UML diagram (Martin Fowler has a great book on the subject). For now I hope I've conveyed lexically the visual nature of UML diagrams.

Class Diagram Example
Sometimes the best way to illustrate stuff is visually (are we getting somewhere yet?), so let's look (visually) at an example of how class diagrams provide the ability to convey information about an object model.

Below are 3 classes and an enumeration in C#. Firstly I show the code files for each class, then below that is a UML Class diagram. Which would you say helps you get the full picture more rapidly and definitively?

public abstract class PersonBase{
public string Name{
}
public string Address{
}
}

public class Citizen : PersonBase{
public CarTypes CarType{
}
}

public class Employee : PersonBase{
public double PayRate{
}
public string Department{
}
}

public enum CarTypes{
Car,
Truck,
Van
}




You can see how the object model is depicted much more succinctly and rapidly with the UML class diagram. You can view all classes at the same time, and how they relate to each other. With code files, you only have the language syntax to help you understand the interactions between classes. While developers can be expected to know the language well enough to understand the object model, when discussing architecture and design, thoughts are much more succinct using modelling then they are using code files.

Sequence Diagram Example
Below is a sequence of events that will occur when washing clothes. This sequence of events are listed out using bulleted points.

• Wear clothes; dirty 'em up
• Load washer with clothes
• pour soap in
• Set washer
  
• Start washer
• Wait for washer to finish
• Move to dryer
• Set dryer
• Start dryer
• Wait for dryer to finish
• Fold clothes
• Put clothes away

Let's take a look at the sequence diagram for the above steps:

Now lets take a look at the above steps in a sequence diagram:



Sequence diagrams are much better at conveying the actual order of steps and the interaction between systems. Another thing sequence diagrams do much better than a bulleted list is looping, which I won't demonstrate here.

UML as Blueprints
When an architect is designing a building, the architect will use blueprints, which is a visual drawing created using complex CAD software. It visually depicts the size of rooms in height/width, the location of pillars in a building, the size and angle (property lines) of the lot the building will reside on, the location of walls, doors, and windows, and many more things that I won't mention. When conveying the design of the building to anyone, the architect will rely on these blueprints to convey every last detail of their building with complete accuracy.

When a construction team is hired to create the building, the construction team will use these blueprints to ensure the architects design is implemented correctly. Along the way, the construction team may point out flaws in the architecture that have to be corrected. In this case, the use of blueprints makes perfect sense. In fact, it could be stated that the use of blueprints is required to construct the building with any level of accuracy in regards to the architect's design.

In the book Code Complete Vol. 2, building software is likened to formal construction of buildings; in fact, the terminology "writing" software is eschewed for "building" software and UML diagrams are likened to software "blueprints". In other words, it is stated that software construction parallels building construction: architects design the software, developers construct the architecture using the architect's output, QA staff perform "building" (quality) inspections, and UAT processes provide the "walk-through".

When thinking about software as construction, it leads you to see the benefit of visual documentation. UML serves this purpose very well, as it allows you to blueprint every aspect of your system, from business requirements down to implementation details such as abstract base classes and descendents, interfaces and realizations (implementors), and so on. It helps you to see how applying development process to building software aids in creating repeatable success; that is, building and shipping software is one thing, being able to do it over and over in a systematic fashion is quite another, and the latter yields more long term success.

Closing
I hope that I've demonstrated how things can be conveyed using visual diagrams much more succinctly and rapidly. I hope that you can see the benefit of class diagrams and sequence diagrams, and I would encourage you to look into activity and use case diagrams. In other words, I hope that you can see the real benefit of UML documentation. It not only provides visual aids in understanding a software system, it can act as a true software blueprint when formal architecture preceeds writing code (and even when it doesn't).

UML can be used to get new team members up to speed on the architecture. UML can give help the business players on your team to really understand what developers are doing in that dark room, and can help everyone speak the same language. Finally, UML introduces formal architecture, which gets developers/architects thinking about the solution to the problem (the implementation) prior to writing any code, which lends itself to accurate and quality implementation.