The Case for Modeling Part 2


Why modeling?

Much software is designed on napkins. A story, a mockup, a model is really all that you need to design how a piece of software works.

This book isn’t about user stories or screen mockups. It is about models, and modeling models. It is one part of the trifecta of software design, and it is a very important part.

What is a model? When you say model to my son, he thinks Legos. That’s not far from the truth. A model is the whole of the component parts that make up software. In the example in Chapter one, the model consisted of trucks, boxes, and the relationship between the two.

The further you get into the so called ‘enterprise’ world (meaning really really big software) the more having a consistent model makes it possible to design intelligent software. This is because a good model brings consistent terminology, an abstraction of ideas and an understandable message to the party.

Creation of a consistent terminology

Working on a model makes you decide what to call things in your domain. In the example in Chapter 1, Boxes could be called Containers. They aren’t. They are called Boxes.

Purists will say that it isn’t just the act of deciding what to call things that matters, but instead the decisions that are made. I disagree on matters of principle here. The simple act of deciding to call something a box and not a container is important. Discussion on what a container is matters. Later on, might you have a bucket? Should boxes and buckets both be containers?

This conversation is frustrating but important. This is the selection of nouns in your new language, and nouns matter. They participate in a common language for your business, both in everyday discussion and in software development

Language and software design

They are called programming ‘languages’ for a reason. Spoken languages have nouns and verbs, as do programming languages. The difference is that precision matters a lot more in programming languages, so the ‘dictionary’ of nouns needs to be exactly accurate.

In programming languages, you define your nouns and verbs. Nouns are class instances, and verbs are methods. In a language like Visual Basic, you define the members of the language as you go:

Public Class Box

Public String Destination

End Class

The system has a concept of a box, and the box has a concept of a destination. We didn’t call the box a container, we called it a box. The box has a destination. This is where the box is going. We didn’t call it an endpoint. An endpoint might mean something else.

Verbs work the same way. You might be able to route a box, for instance.

Public Class Box

Public Destination As String

Public Function Route() As Boolean

Return True

End Function

End Class

Now the Box knows a verb – you can route a box. It is an action word – something you can do. We are literally building a new language here – the hip term is a Domain Specific Language, or DSL. It is not a general language. It is specific to our needs.

There is a problem here, though. The Visual Basic code is something that is only used by the developers. Left to their own devices, programmers will come up with the language to describe your business all on their own, and then it won’t be a common language, used by the business and the IT staff.

The key is in a common language

The reason that domain languages are important to modeling is that the software comes out a lot better if both the business users and the software developers use the same words. I probably don’t even have to mention this, because most all of the fine readers of this book have had that conversation:

“But that process only occurs if the router has that one form.”

“Which form?”

“Oh, I don’t know. That one form with the routing information. “

“Which routing information?”

“I’m not sure. It’s a little different every time.”

A common language mitigates this conversation, because they know to say “destination” and not “that information that is needed for the route.” Things have a name. Those names reduce confusion, and cause better software development.

Description of ideas in an abstraction

Creation of a model provides an abstract space to work with the ideas in the system. The architect and the business analyst don’t have to depend on concrete examples with exceptions left and right to design the software, they can work in generalities.

Boxes can be routed, for example. The development team doesn’t have to deal with the fact that Box ABC123 went to Cleveland, and Box DEF456 went to Cincinnati. The exceptions in specific cases are important, and need to be modeled in their own right, but they don’t need to be in the general abstraction that is used to talk about the system in at the 1,000 foot view.

Making models understandable

Abstraction is important when talking to users. To define user stories, the business analyst needs to talk to users all along the process tree. Most users don’t have visibility into the whole process. The receiving guy doesn’t know how Box ABS123 got to Cleveland, but he probably understands that the box was routed. Even if he doesn’t, this idea can be explained, because it is understandable.

Development teams get entrenched in detail. This detail is a necessary as the software gets developed. With an understandable model, though, there is always somewhere to go when you need to return to ‘home base’ and cover the big picture again.

Images versus text

Usually, architects develop diagrams to show models, like Figure 1-4. This is fine, but it gets to be far to complex after the details is added. Few diagrams can be easily searched, organized or simplified. Since we are looking for an abstraction, simplicity is king.

Figure 1-4: A model diagram

An option for a model is to eschew the boxes and use text. Models developed in text can be more easily simplified, and are much more searchable.

Text has a lot of benefits when you are creating an abstraction. First, the viewer doesn’t get tied up by the lines. Often, relationships between items (represented by the lines) are far too complex to make a readable diagram. If you have a simple list of the items that are related, you can just read them rather than tracing them.

The other benefit of using text for the abstraction is that there are fewer blocks to broadening the abstraction. When you realize that the box actually has a relationship with a product, you can just add it, rather than finding the product box on the other side of the page and finding a place for the line.

The conversation between the architect and the developer

The third consideration of creating an abstraction is the conversation amongst the development team members. The problem domain is rarely known when a group of developers get together to solve a particular business problem. Usually a new feature is just that – new – and the terminology being used is foreign to all but the business people directly involved with the process.

Use of a model mitigates this issue by firming up the terminology right from the start. If all of the entities in the business domain are defined and named, the conversation can revolve around the abstraction rather than examples. Even if the business unit itself uses mixed terminology for parts of the business domain, the model will sort out the communication between the architect and the developers.

This conversation is rarely called out, but it a very important conversation indeed. In small and large projects, the big picture is usually in the architects head rather than written down. The architect tries to pass the feature specific information to the developer, shielding them from the big picture. The developer tries to build a focused feature without insight into the overall system. Hilarity ensues.

The construction of a well-understood model provides an abstraction that the architects can use to give the developers context. Context is very important in system development. It doesn’t get in the way of the detailed development work that the programmers are completing, but it does lead to the discovery of contextual errors. Developers can find problems that relate to the system as a whole and apply the fix holistically, rather than just locally in their own feature.

Forming an understandable message

Creating a model allows for communication to be constructed that actually makes sense – especially as it relates to change. In order to communicate to the users and developers about a system, it is necessary to clearly describe the focus points of the system. To clearly describe anything about the system, it is necessary to start with a model.

To some extent, this pales with the need to provide the next guy with a path. Documentation of systems at the design level is notoriously bad. It is never up to date, practically never complete. It is confusing and passes on no knowledge of the business domain. It is useless. Software modeling – done correctly – mitigates this considerably.

Communicating to the user

The user is the person for whom the software is written. It is important that the development team can communicate on a few different levels. First, the user needs to be able to pass on business functionality to the architect. Second, the development team needs to confirm functionality after consuming it into the rest of the system.

During the initial communication about the system, the first thing that needs to be completed is a software model. The entities in the model will provide a base level of communication about the rest of the software. As functionality is discussed, there will be no need to focus on specifics because the model is specifically understood, not just generally assumed.

As important is the review of software designs. When user stories and mockups are reviewed with the user prior to commencing development, there is an understood terminology behind the discussion.

Communicating to the developer

The conversation between the architect and the developer was discussed above, but it bears mention again in this context. Creation of a context for the developer to create features makes a huge difference.

Context isn’t the only issue, however. Users communicate with developers too - especially in agile environments. Testers communicate with developers. Managers talk to everyone. Wouldn’t it be nice if everyone could just use the same terminology? I certainly think so.

The model brings an accurate terminology to the whole team, especially when communicating with the developer. As with the other examples in this section, the terminology reduces errors and the time it takes to communicate ideas.

Communicating to the future

Probably the largest afterthought in system documentation is the next guy. After all, the development staff isn’t being paid to make version two easier, are they? They are being paid to write version one. Nonetheless, having to edit a system is a necessity. Either the technology will move on and the update wizard will come calling, or the business rules will change.

The best way to improve on systems documentation is to remove the problem of updating it on a regular basis. A quality software model will assist with that because it will update as the code is updated. Working from a model removes some of the need for comprehensive documentation.

The business case

It is tough enough to explain to the CIO why you need to upgrade to TFS 2010. Describing just how important it is to totally change the development methodology of the organization even few years is really a problem.

In Software Language Engineering, Anneke Kleppe points out that we need to upgrade our development methodologies now because it’s the shiny new thing, but because we are doing more with less. Dijkstra (1972) called it the Software Crisis, and it is getting worse.

Taming complexity

Year after year, software developers are asked to tackly more complexity. Kleppe describes an environment where it used to be enough to have ‘Hello World’ show up on the screen. With the advent of GUI, consider all of the technologies that have to be mastered to get it on the screen - CSS, windowing, threading perhaps, markup, the list goes on.

What’s more the additional computing power has led to additional expectations of users. Now you are expected to deliver identity and membership, with ‘Hello Mr. Sempf’. Or even delivering more, localization and personalization, with ‘Good evening Mr. Sempf.’

Modeling software tames complexity. Part of the growing complexity of software is that no one person knows the whole system. It is a common story: features need to be added, but the UI guy is on vacation and now there are 24 business rules in the RDBMS.

Accurate models make for understandable software. While nothing makes software easy, not having an accurate model will certainly make it harder to understand.

Enhancing communication

From the project management perspective, nothing makes life better than communication. Weather agile or waterfall, trust and transparency are key. Both of these characteristics require communication. Communication is hard when half of the people at the table calls a container of items a ‘box’ and half of them call it a ‘carton.’

Modeling software enhances communication. Even if all that is done is the simple act of validating the common language it will make talking about the project a lot easier. I hope that you would take it even further than that.

As a project grows, features are added. To build a system of language that assures that the concepts in the application are referred to the same way throughout time. This is essential to good communication, and ease of updating.

With real software modeling, and a metadata implementation, the model follows the software. This means that throughout the lifecycle, the semantics are an intrinsic part of development through the domain specific languages provided in the model.

The Case For Modeling Part 1



What led to this





A description of the problem






Figure 1-1 The whiteboard - truck contains boxes.



Figure 1-2: The document - truck contains boxes


Moving to code


namespace Warehouse
    public class Truck
        public Box Boxes { get; set; }
    public class Box


Figure 1-3: The database - trucks contain boxes



  public partial class Truck : EntityObject
        public static Truck CreateTruck(global::System.Int32 id)
            Truck truck = new Truck();
            truck.Id = id;
            return truck;

        [EdmScalarPropertyAttribute(EntityKeyProperty=true, IsNullable=false)]
        public global::System.Int32 Id
                return _Id;
                if (_Id != value)
                    _Id = StructuralObject.SetValidValue(value);
        private global::System.Int32 _Id;
        partial void OnIdChanging(global::System.Int32 value);
        partial void OnIdChanged();
        public EntityCollection<Box> Boxes
                return ((IEntityWithRelationships)this).RelationshipManager.


The gap is wider than you think

There are two things that are clearly wrong here.



Mapping code to models



The core problem is that gap


  • What happens if there are several different databases?


Various solutions




Microsoft’s tries









Modeling with CASE and the gorilla in the room


The Unified Modeling Language







<whatever> Driven Design






Bill Sempf


