An Introduction to the C4 Modelling Language

2020-01-06T12:28:40+00:00

The C4 model was created between 2014 and 2017 by Simon Brown.

The C4 model was created as a way to help software development teams describe and communicate software architecture, both during up-front design sessions and when retrospectively documenting an existing codebase. 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.

The C4 Model

The C4 model is a modelling language with a few distinguishing characteristics. For instance, the four core diagrams are hierarchical and allow the user to explain a software system using different levels of detail, which optimizes the delivery of the information to different audiences.

The Four Core Diagrams

Context (highest)
Containers
Components
Code (lowest)

Context

The Context level is the most abstract and shows the least amount of detail. This level shows which users are using the software, which of the systems are external and how the systems interact with your internal system. This level has been very helpful in my experience when you’re:

introducing your team’s landscape to a new team member (both for technical and non-technical folk)
explaining your landscape to a different team in the organization

Level 1: A System Context diagram provides a starting point, showing how the software system in scope fits into the world around it.
— c4model.com

Containers

At the Containers level the internal system is no longer mapped as a black box. The internal system is exploded into containers, meaning deployable units (APIs, web applications, mobile applications, database schemas, filesystems, etc.) are shown individually.

The Containers level diagrams can be very helpful during team sessions (e.g. refinements) to get everybody on the same page and to reduce miscommunication. It can also be helpful in onboarding a new colleague, it’s like giving someone a map of a country/region they’re in for the first time. This serves as a tool for collaborating on deciding where the change should be implemented, and how the change should - or should not - affect its up-/downstream dependencies. When I’m new on a team and there are no architectural diagrams, I create the Containers diagram first to map out the landscape. This tends to lead to interesting discussions with other developers regarding the landscape and quickens my understanding of it.

Level 2: A Container diagram zooms into the software system in scope, showing the high-level technical building blocks.
— c4model.com

Components

The Components level zooms in on an individual container. All users and up-/downstream dependencies (internal containers and external systems) are dropped from the diagram, except for the ones a Component interfaces with directly.

This diagram allows for a lot of detail. I tend to let it depend on the situation whether I choose features, layers or classes as Components. There can be multiple Component diagrams for a Container if that proves valuable. My rule of thumb is: as long as the diagram does its job at explaining the internals of the Container significantly better than opening the solution in an IDE, this diagram provides value. Otherwise, it would only add to the maintenance burden of updating it every time the code changes.

In my experience, this diagram has been mainly helpful when dealing with messy, counter-intuitive codebases. It did not prove valuable when solutions were well designed, small, or were following a clear pattern (such as Ports & Adapters). When creating a Component diagram, start with the composition root, and map all the code paths that go to either up- or downstream dependencies. The rest are probably helper classes and can be left out.

Level 3: A Component diagram zooms into an individual container, showing the components inside it.
— c4model.com

Code

The Code level removes all users, all external systems and internal containers. Furthermore, it focusses on adding technical depth to a Component. Disclaimer: I’ve never felt the need to create a diagram at this level of detail, since this kind of diagram can be generated from code. For instance, by using a tool that interprets your code base and generates a PlantUML definition of a class diagram.

Level 4: A code (e.g. UML class) diagram can be used to zoom into an individual component, showing how that component is implemented.
— c4model.com

Cmder: how to show changed Git files

2019-03-21T14:25:00+00:00

From the cmder website:

Cmder is a software package created out of pure frustration over the absence of nice console emulators on Windows. It is based on amazing software, and spiced up with the Monokai color scheme and a custom prompt layout, looking sexy from the start.

Cmder is my favorite terminal emulator for Windows, and my use has been born out of the benefits it provides over using the standard cmd and powershell terminals.

However, Cmder is a tad spartan when it comes to showing the amount of changes when you’re in a directory holding a Git repository.

Note: this does not apply to powershell terminals.

Showing Git changes

Default behavior

When adding a file and removing a file from the working directory, the terminal prompt shows that something has changed (and on which branch).

This could benefit from showing a bit more information. For instance, it would be great if our terminal window would also indicate what has currently been changed.

Improved behavior

Using a gist I found on GitHub, more insight can be gained about the changes in the current working directory.

With the addition of the script, we’re looking at the amount of files changed. Specifically, in green, we see which files have been added (+), modified (~), deleted (-) from the current index (read: staged for commit).

In red, we see the same numbers regarding added, modified and deleted files. These changes are scoped to the currently untracked files in the working directory.

How it works

The following line in the script executes a command using the standard Git command-line tooling:

git -c color.status=false status --short 2>nul

The output of the command is translated into the graphical representation on the command prompt. Look below to see them in action simultaneously.

How to apply the script

Save the contents of the script into a file (e.g. git_peek.lua).

Find the directory where Cmder is installed, and place the file into /config.

You’re done! The script will be executed when Cmder starts up.

Credits

This script was not written by me and credits go to the original author. I’d like to thank the author for the gist that the above post is based on.

On Developing Software