Why did Casavo choose C4 for documenting its software systems?
We need standards to explain things
Communication of complex ideas is a major need in every professional field. A condition sine qua non.
Take the chair design in the opening image of the article, and give it to an expert artisan. It’s a safe bet to say she will be able to craft the object, even without knowing the designer.
If a building has to be built, an architect will deliver a detailed project in order to communicate her ideas. This set of documents will follow some conventions and standards, that are somehow agreed and shared with other similar professionals. The goal is to achieve mutual comprehension and cooperation, no matter the location, cultural differences, and different backgrounds.
IT is a young industry, and its standards are continuously evolving
In all industries, it is common to find several conventions adopted to facilitate sharing of ideas. In the previous paragraph I brought the example of civil engineering, but IT doesn’t make an exception, and it needs standards as well. Software architectures are among the most complex systems that humans have built, and the need to clearly describe them has always been a priority. Nevertheless, this is a very young industry, and things are evolving at the speed of light, including the way we represent things.
The truth is, in Tech a real consensus about a “definitive standard” has not been achieved yet.
UML or, “when I was a student I thought I found THE solution”
I remember with a sort of compassionate benevolence my “Young Self” that, around 13 years ago, believed to have found the final answer to this topic.
When I studying at the university, Unified Model Language (https://www.uml.org/) was presented to me as “the” language in software engineering to provide a standard way to visualize the design of a system.
As of today, it is still the most comprehensive solution to document software systems in detail, and it has also been approved as an ISO standard.
Everything’s great then, right?
Well, not so easy. There are at least three points to be kept in mind:
- UML diagrams can easily become quite complex
- A large system would require A LOT of different UML diagrams to be described
- It is very easy to lose the high level view of the system as it scales
In other words, UML is good but it requires a lot of effort and skill to be correctly adopted and maintained. Please keep in mind that a software system is really different from a building. It is a fluid entity, which evolves over time, and documentation can quickly become obsolete if no capacity is assigned to the task of keeping it always updated.
Also, the race for Agility has reduced the priority of having a comprehensive documentation in place.
Working software over comprehensive documentation
One of the core values of the Agile Manifesto puts the emphasis on the importance of the code rather than the documentation that explains it.
From a developer point of view, if the code is written in a high quality way, it is the best documentation ever.
Still, as a system evolves in complexity, a visualization that captures the high level photography is quite useful, if not absolutely vital.
Then comes C4
C4 (https://c4model.com/) is a new proposal in documenting architectures, introduced by Simon Brown in 2018; it lays its foundation on UML and the 4+1 architectural view model.
Its main advantage is that it is an abstraction-first model: it reflects how software architects and developers think about software.
Architects are very used to adopting different zoom levels in their reasoning, and this model definitely fits with this approach; in fact, it has four view perspectives defined by the following levels:
- L1: System Context — Shows the system in scope and its relationship with users and other systems. This level is very useful also in discussions with business people, as it can give a clear idea of the interactions that exist between actors and systems
- L2: Container — Decomposes a system into interrelated containers (executable and deployable sub-systems)
- L3: Component — Decomposes containers into interrelated components, and relate those components to other containers or other systems
- L4: Code — Provides additional details about the architectural elements that can be mapped to code. It is interesting to note that, at this level, C4 relies on existing notations like UML itself. Thus, it would be wrong to consider C4 model as a pure alternative that excludes the others
Why we chose C4
In Casavo we are:
- Embracing Agility
- Building products that simply didn’t exist, and that are evolving day after day
Based on these two elements, it is quite clear that we needed something that was flexible enough to 1) convey information across developers and 2) avoid useless overhead when it comes to updating and maintaining the documentation itself.
Also, Casavo has a strong foundation in business functions, and our goal as a PropTech Company is to be able to communicate our technological ideas to all kinds of stakeholders, not only those with a tech background.
If we then also take into consideration the speed at which we want to move forward, it becomes easy to realize that something like UML wouldn’t have been the right choice. C4 was pretty perfect and in line with our mindset.
Is C4 the future of software systems notation?
Personally, I believe there will still be a lot of debates, proposals and models before arriving to a general consensus across developers and software craftsmen all over the world.
I really have nothing against UML; it has helped me a lot in the past and I am convinced it can provide a lot of benefits if used correctly — but even when I used it frequently, I never found value in using it 100% comprehensively. I always found myself to adapt it to the specific needs of the situation, just relying on a limited subset of diagrams.
I am pretty sure C4 will not be the “final destination” in software notation, but I am also quite confident it is a great step forward. As tech people, we need to agree on standards, and investing time in reasoning about the best ones is definitely a gift we do to the whole industry.
My personal suggestions to both senior and junior developers when approaching these kinds of themes is: please, deal with them with a fully open mindset. We are a young industry, we are shaping our cultures, values, methodologies and approaches. We are changing the world piece after piece. Please let’s not assume that what looked best just 5 years ago will still be useful tomorrow; that might not be the case, and that’s fine.
