DEV Community: Viezly

Introduction to C4

Sanat Serikuly — Wed, 20 Oct 2021 00:00:00 +0000

Recently, I joined a new project with a lot of legacy (not old, but legacy) code. The project kicked off only 6 months ago, but the chosen architecture was at least unusual. "Yay, something new" I said to myself and started digging through the code and architecture.

Quickly, I realized that it is really hard to keep everything in mind. In fact, humans can keep only 7(+-2) things in short-term memory. I had some experience with visualization tools like diagrams.net (formerly draw.io) or Excalidraw, but the problem is that I was jumping between different levels of detailing and it was drawing me off.

C4

Surfing the web around, I bumped into a C4 model and this video on YouTube (highly recommended). C4 is a framework that allows abstract modelling and diagraming to a certain level of details. Would you care about a specific controller when you model complex user journeys with multiple systems involved? Probably not. C4 provides a very simple (but powerful) way to be at just the right level of abstraction.

(Illustrations are from the C4 Model website)

The framework provides the following abstractions at its core:

Person - any user of your system. For example, actors, roles, personas etc.
Software System is the system the person interacts with. In many cases, the software system is owned by a single software development team. For example, a digital bank, an internet shop or a video-streaming service.
Container (not a Docker!) represents an application or a data store. The main thing about containers in the C4 model is that they are separately deployable/runnable at runtime. For example, server-side applications, client-side applications, mobile apps, microservices, databases etc.
Component is a grouping of related functionality encapsulated behind an interface. Typically, components are running in the same process space of the container. The main difference between component and container is that components are not separately deployable units.
Code is actually a class diagram of the application.

Using abstractions it is possible to build different views on a software system on different levels.

C4 provides 4 levels of the software system. Let’s have a quick look at them.

Level 1: System Context diagram

In the system context diagram the focus is on a software system as a whole. Any people using the system would also be a good fit for this diagram. It gives a good perspective on a big picture of the software that is being built.

The System Context diagram could be helpful to present to very broad and generic audiences.

Level 2: Container diagram

Once it is clear how the software system fits into the whole environment, a useful step is to zoom in a little bit. This is where you can see databases, microservices, modules and how they communicate with each other. Container diagrams reflect high-level architecture of the software system.

The Container diagram would be helpful for discussions with architects, product owners and business analysts.

Level 3: Component diagram

After laying down high-level architecture, it is possible to zoom in even further and look at actual components of the container. Here we have major structural blocks like interfaces, endpoints, business logic components etc. This type of diagram is very helpful when the architecture is explained to software developers.

Level 4: Code diagram

Finally, if we zoom in even more, we’ll see actual classes, controllers, repositories etc. This level is not recommended for most teams since the level of details is too high. It might be useful though in some specific cases when the code-lever architecture is very complex.

Even though C4 highlights only 4 levels, it might not be true for every project. You might end up with 5, 6 or even 7 layers in your project. Just make sure you choose the right zoom depending on the audience.

Summary

In the modern software development world, where systems become more complex and complex, engineers need something to structurise the work. C4 provides a simple, but powerful framework that is easily understandable.

If you are interested in automating the C4 Component Level, you can look at Viezly. We automatically generate a diagram of the changes and provide an advanced tooling for a code review.

In the next article, I am going to provide a practical example of how to use the C4 model and what tools are available. Stay tuned.

One big reason to review the code

Eugene Haisenka — Thu, 29 Jul 2021 14:08:20 +0000

Code review has been there for a while. But many people struggle to explain why they are doing it in the first place. It's like a default action, that is required for mystical "good code quality". Yes, it's fairly simple to justify to yourself or other people why you and your team need code review. But often these reasons don't really have solid proof of effectiveness. Or just doesn't work when a team doesn't meet even their standards of code review quality and involvement.

I'm going to talk about one real and universal reason why you personally should review the code of your teammates. Also, I'll share a small example and a study related to this reason.

Why do people review code in general?

Let's enlist common reasons to review code changes. These are:

Check security issues
Implementation check
Architectural review
Code style review
Performance review
Errors and bugs and mistakes catching
Maintainability, changeability
Knowledge sharing

All of these reasons aimed to mitigate "future issues". Improving code quality helps the application to run with fewer bugs and performance issues. And better code quality brings joy for developers — good code easier to read and maintain :)

So these reasons mostly aimed for better code review. That's great. But what in the code review for you personally? The last line in the list is "knowledge sharing". Usually, this means "senior devs help less experienced folks write better code". But what about just reading?

The ultimate reason to review the code

Well, reviewing teammates' code makes you more familiar with the codebase. And thus making you more satisfied with the code quality! Apparently, how people perceive the "code quality" is not only measured by the complexity of this code but also by how people are familiar with the code. Familiarity plays a big role in our acceptance of the code.

Devs, who review code more often, tend to evaluate their codebase more "quality" than those who review less. A team might have several similar codebases in terms of code quality. But perceive the code which they simply didn't work very often as "bad code".

Studies and examples

You can watch an interesting story about code familiarity and code quality perception. The speaker tells a story about the team, which has several codebases. The team evaluate one codebase as "good", and another as "bad". But after code complexity analysis, turns out that the codebases are pretty similar code in terms of quality and complexity. But the good code is the code on which the team worked daily, and the bad code is the code they inherited from another team in the organization, and thus have no familiarity with it.

Also, as mentioned in this research, devs who are satisfied with code review (and perform it more often), usually more satisfied with their codebase. And those, who are satisfied with the code review process, tend to do code review more often than those who didn't.

Code review is better for you. And you don't need to go deep into the code.

So, the reason for you to read code is (at least) to track changes and "index" codebase. It's not necessary to dig into the details of each, especially when the codebase is enormous. But reading to have at least the idea of code structure can improve your feeling about the whole codebase. It's a great way to not be sad about code quality in the future :)

Reviewing big pull requests. What, why, how.

Vladimir Penyazkov — Wed, 14 Jul 2021 17:17:39 +0000

In this article, I will try to figure out what leads to big pull requests, what benefits they might provide, what can help you to review them.

First of all, why on earth developers should care about the size of pull requests? In short — it has an enormous number of benefits, and all of them are well described in Google's article: https://google.github.io/eng-practices/review/developer/small-cls.html. To mention some of them:

Reviewed more quickly
Reviewed more thoroughly
Less blocking on reviews
Easier to design well

and more...

Talking about the size, when pull requests are considered big, it's hard to give a precise number. Often it depends on the type of changes, the project, personal experience. In some cases, 1k changed lines can mean a huge pull request, in others — an acceptable one. Usually, it starts to get harder to review changes when the number of changed files is increasing, rather than the number of changed lines in a couple of files.
Further in the article, a big pull request will mean a relatively large amount of changed files (20+), the number of changed lines doesn't matter.

Is it always possible to make a pull request small enough?
In Google's article, they say it's extremely rare when there is no way to split a pull request into smaller parts. Personally, I'd agree with that, but from my experience, there are some situations when it's almost impossible to split changes, or even it's better to keep them in a single pull request, to name a few:

A change in a common component of the application. It might be a front-end component, or backend helper class, or whatever else. Such changes usually stretch across dozens of files and it easily turns into a big pull request. It might be possible to split these changes, but reviewing that at once can provide its own benefits: often you can notice a missing set of changes which you won't find reviewing it in parts.
Small and frequent pull requests are sacrificed for the sake of productivity. While small pull requests provide a lot of benefits, there is at least one drawback as well: they require more time to create all of them, maintain the stability of the build, and they more often distract colleagues from ~~watching youtube~~ whatever they usually do at work. If you're a small team, you want to deliver features faster, you trust each other and have a common vision on how things should be developed — then probably you can skip review at all or review only the final pull request to double-check important things (such as architecture decisions, API design, etc.) from a different perspective.
Poorly established development process. It's either a lack of management experience a team-lead has, a lot of newcomers in the team, or simply you just setting up a team. In such situations, you cannot be sure you won't receive a big pull request on review.

In all cases described above you as a reviewer end up with a big pull request which you have to review. Usually, it's an endless list of changed files which you have to go through, scroll up and down, and make a whole picture of it in your head: why this file has been changed, how the files are interconnected with each other, who's calling this function... It usually hard, takes time, and let's admit that it leads to a shallow review being done if at all.

Just to remind you how it looks like here is an example. It's a pull request of just 16 files:

Where is the best place to start the review from? Always start from the top isn't the best way, isn't it? How to understand what's been done here? Why some file's been changed? Where is a new function invoked?
These are important things to know to perform a high-quality code review, but you don't know them until you read all the changed files and built a full picture in your head.

But what if that picture is built for you automatically? It could be literally a picture where all relations between files are shown and you can understand the scope of changes just after a look and decide where to start.

Sounds cool, right?

That’s what Viezly does.
Viezly is a review tool that splits the changes into smaller independent parts and provides diagrams where the relations between files are shown. With all this, a reviewer can faster get the understanding of what’s been changed and start to review by navigating from one file to another in an optimal way instead of scrolling a list of changes up and down to find out what's going on.

Just compare the example above to this one:

After just a single look at the diagrams, you see what packages have been changed, how the changes are related to each other. You can start reviewing from the root file or the most nested files as you prefer. Furthermore, the changes are divided into standalone groups to make them more comprehensible.

Is that what you trying to keep in mind when reviewing the changes, isn't it?

If you find this useful, as I do, check out more details at viezly.com and stay tuned!