Modeling is dead, Long live Modeling!
Modeling is an integral part of every engineering discipline. And software engineering is no exception. Modeling fills the gap between having an idea and realizing it. A model expresses an idea in abstract terms in a common language, so it can be shared, analyzed, validated, and verified. Even if an idea is not explicitely expressed, software engineers construct a mental model that is then translated into code.
With an abundance of modeling languages – ranging from well-established approaches such as the Unified Modeling Language (UML; standarized as ISO/IEC 19501) and SysML to less popular and even obscure ones like Petri Net – it is possible to model every piece of software, protocol, data store, etc. Yet, software engineers are rather reluctant when it comes to modeling. Why?
In the following, I reflect on my experience to understand why modeling has not won over software engineers. I also discuss how I managed to overcome this reluctance in the context of architectural modeling for my Prototype Fund project, Xenguard.
Why do we model?
Imagine that you want a build a bridge across a creek. Your goal is to get from one side of the creek to the other without getting wet. You have a set of requirements: the bridge must be able to support your weight and your dog’s weight at the same time, and it must be high enough for a raft of ducks to pass beneath it. It must also be weather-resistant. And so on.
With an engineering mindset, you would start with measuring, calculating, drawing, or even building a small-scale model to make sure that the bridge fulfils your expectations before actually building it. You could even handover your blueprints, i.e., the model, to someone else to build the bridge for you.
The same goes for software systems:
Software modeling involves creating abstract representations of the most significant aspects of the software under study. It provides a means for software engineers, the development team and other stakeholders to analyze, reason about, and understand key elements of the structure, behavior, intended use, and assembly considerations of the software. Modeling facilitates making important decisions about the software or components. It also enables effective communication of software information to various stakeholders.
In this sense, a software model serves as a common language for software architects, developers, requirements engineers, and even non-technical stakeholders, such as salespeople and customers. It allows you to validate and verify the software before development begins. As such, it also reduces development costs by avoiding unnecessary iterations to fix shortcomings that could have been detected during the modeling phase.
Why don’t we model?
Actually, we always create models of our software. More often than not, however, the model remains mental. In my experience, software models are usually reduced to loose notes, photos, or screenshots of “boxes and lines” during brainstorming sessions. Some models are then produced retrospectively during or after development for documentation purposes. Examples include API models (in OpenAPI) and sequence diagrams (in UML). But none of the projects I worked on in academia or industry had proper modeling in the strict sense.
I assume there are various reasons why we, as software engineers, don’t model our software. I chose three arguments against modeling that also resonated with me, and go through them briefly below. In the next secion I report on how I addressed these hurdles.
“Modeling costs outweighs its benefits”
Modeling takes time and effort. Why not invest it in directly development? We can always reiterate if requirements are not met or if we overlooked something. After all, one of the core values of Agile Software Development puts “working software over comprehensive documentation”.
This argument makes sense at first glance. But in practice it’s a recipe for technical debt. For example, a new developer that joins the team or want to contribute to your open source project needs to mentally reverse engineer the model from the codebase before being able to get on with actual development. The same applies if the software needs to undergo security or compliance audits, or if new requirements are introduced.
“Modeling languages are complex and unintuitive”
The UML specification is ca. 800 pages long. Even a simple modeling framework like the Entity-Relationship Model is unnecessarily complicated by having multiple, incompatible notations. No one speaks this allegedly “universal” language.
Personally, this argument resonantes with me and aligns with my own experience. While there are UML diagrams that are simple enough for me to remember without having to go through the docs (e.g., activity and sequence diagrams), I am more than often unsure about the notation and the canonical representations.
“Modeling tools are not developer friendly”
You need a designer for creating visually appealing software models. And as software engineers we are more comfortable with writing code then creating diagrams.
This argument is only half correct; not all modeling languages are visual. Formal specification languages, for instance, are part of the modeling toolbox and are not primarily used for creating diagrams. Nevertheless, I agree that designing visually appealing and comprehensible diagrams is far from trivial.
Taking the (modeling) plunge
Prototype Fund projects are all open source. They should be able to survive even if the original developer abandons the project. Respectively, I wanted to make sure that anyone who comes across Xenguard has a chance to quickly get a grip of the project and be able to contribute without having to extensively go through the source code first. This was the benefit that modeling provided me, and the answer to the first hurdle. I started with UML but quickly switched to a much simpler language, the C4 model, addressing the second hurdle. Finally, I used the Structurizr toolchain, solving the last aformentioned challenge. I discuss each point briefly below.
Modeling as enabler for community building
For my Prototype Fund project, Xenguard, I chose to do proper modeling because my goal is to build a community that can contribute actively and maintain the project. Good models allow potential developers to quickly understand the project, its components, how they interact, and their relationship to external components. I consider modeling an incentive for future Xenguard developers, and the long-term benefits already outweigh the costs.
C4 Model as a simple alternative to UML
My first choice was naturally UML, de facto the most prominent modeling language for software engineers. It didn’t take long for me to realize how lost I am with UML notation and its complexity. I abandoned the idea and settled for a much simpler modeling framework, the C4 model:
It’s a way to create “maps of your code”, at various levels of detail, in the same way you would use something like Google Maps to zoom in and out of an area you are interested in.
C4 diagrams are very intuitive. You start with a high-level abstraction and work your way down to more specific models. There are 4 abstraction levels: Context, Containers, Components and Code (see the C4 homepage for more). And the notation is, well, nonexistent, meaning that you can use your own symbols and styles as long as they are consistent among diagrams and well documented. And so the second hurdle was cleared: I now have a simple and intuitive modeling framework.
Structurizr as modeling toolchain
The last step was to create the diagrams. It turned out that the author of the C4 model had already catered for that. Structurizr is a tool with its own domain-specific language (DSL) that allows you to write models as code and provides tools to render and modify them visually. And this took off the final hurdle of tooling for me.
Final thoughts
While modeling can be a tedious tasks with no apparant advantages, with the right tools and the long-term goal in mind, it is a must for any software project.
If you had a similar experience like mine with modeling, you might want to take a look at how I wrote Xenguard models in Structurizr DSL, and how Structurized generated an interactive webpage as well as graphics for the documentation. The language was easy to learn, and the tooling made it really fun to work with.
The C4 model is not intended to replace UML, SysML, or other comprehensive modeling frameworks. However, it is much easier to get started with than those frameworks. It also has all the necessary tools for generating documentation content. Give it a try!