Less is more: what breaks good code (and good architecture).

Maybe you know the situation: You open a project that someone else developed and after a few minutes you think to yourself:

Advertisement

“But it’s too complicated to implement!”

Software-architektur.tv: Autonomous teams – do we really want this?

The more you read the code, the more you realize that much of it is unnecessarily complex. There are often levels of abstraction that obscure things that could actually be practical and easily solved. Such an approach makes code difficult to understand – and this applies not only to code, but also to the architecture of a project. You may have also felt like someone was trying to create too much complexity instead of focusing on writing good code.

Today everything is exactly like this: architecture should ideally be invisible. But what does it actually mean? And how can you use this principle to your advantage?

good architecture is invisible

Let’s start with the question of what it means for good architecture to be invisible. Comparison with reality helps to clarify this. Think about impressive buildings: perhaps a modern villa where every detail fits and all decisions go together seamlessly. Or a historic building like Cologne Cathedral, which is also architecturally fascinating. The important point is this: in both cases you appreciate the building as a whole. You know there is a well-thought-out architecture behind it, but it doesn’t seem obvious to you. Rather, everything feels like a coherent overall picture in which you can feel that all the details have been considered. This means that good architecture fades into the background and doesn’t constantly command your attention.

Of course, an alternative might be to build a building in which every architectural decision is clearly visible. This may sound tempting, but it will give the impression of an overambitious study that is more an end in itself than the foundation of a great building. And that’s exactly what I mean when I say it: good architecture is invisible. It creates structures without pushing itself into the foreground.

Architecture meets software architecture

This principle applies not only to buildings, but also to software. Here too, architecture is not an end in itself. It should provide a solid foundation on which to build well-structured, maintainable, and long-term usable software. If an architecture meets these goals without taking itself too seriously, it is successful. On the other hand, if it misses these goals or places unnecessary emphasis on them, it is bad.

By this point, it all probably seems pretty obvious. But if it were that easy, we wouldn’t so often get projects that make us think:

“What’s that? What was anyone thinking?”

Over the years, a pattern emerges: people who are just starting programming often develop simple and practical solutions – simply because they can’t do it any other way. However, as their knowledge increases, developers gravitate towards more and more abstract problems. This is what we are taught in training: sending a Word file is summarized in “sending the file”, which in turn becomes a message from the sender to the recipient – and in the end we only briefly talk about the “message”. Let’s talk. Originally you just wanted to send a Word file via email.

Yagini – You won’t need it

The problem is often too numerous and, above all, too quickly solved. Each abstraction introduces further hints, making the code harder to understand. Instead of being able to understand the developer’s actual thought process in code, you first have to mentally translate it to another level. The more such layers there are, the more difficult it becomes to understand the code. However, code is written only once but read many times. The focus should therefore be on readability, comprehensibility and comprehensibility, not on abstraction as much as possible. The “You won’t need it” principle (YAGNI) is a guiding principle in software development for a reason: keep it simple! This principle applies to code as well as architecture.

A central aspect is the clear definition of responsibilities: which task, class or service is responsible for what? The principles of low coupling and high cohesion help here: individual elements should exist as independently as possible from each other, while everything related to a task is brought together in one place. So if you need to fix a bug, changing it in one place without affecting other parts of the system should be enough.

a practical example

A real-world example illustrates this: In a code review, I discovered an unnecessary abstraction in the Go codebase. Instead of using a pointer to express that a value is optional, the developer introduced a Could type – a concept from functional programming. However, this type was used in only one place in the code, which was neither consistent nor useful. A simple indicator would have served the same purpose and been more understandable and less error-prone.

The problem of unnecessary abstraction occurs not only at the code level, but also at the architectural level. So sometimes microservices are introduced not because it is necessary, but to implement the concept of microservices. This creates unnecessary complexity and misses the real goal of improving the structure and understanding of the software.

Readability beats writeability

Why do experienced developers take action so often? One reason is the desire for perfection, the other is the desire for identity. It is important to be aware of this impact and consider your own code and architecture. Code reviews and pair programming can help here as they promote a practical approach and understanding for others.

Architecture and code are a means to an end, not an end in themselves. You should focus on the technical requirements and needs of the team. Solutions should be developed iteratively and pragmatically. Always ask yourself: does the team really need this abstraction, or is it just complicating things unnecessarily?

(rme)