English
Software architecture is like your underwear. It’s always there, but you won’t notice it until something is wrong. But unlike underwear, good software architecture is surprisingly rare, and there are a million reasons for this. We’ll focus on one common issue: responsibility. Who should be responsible for the architecture? And what happens when the responsibility is not distributed right?
We’ll look at this through some problems with their causes. In the end, you’ll find some solutions, too. Some of these might be painfully familiar to you. If not, consider yourself lucky. Sometimes, the simple and clear-cut answer would be to switch the architect to a better one or hire more people. However, these are not often the best solutions. That’s why we also present alternative ways to solve these problems.
In these scenarios, your team consists of skilled software developers with clear goals. They understand coding and send funny memes on Fridays. However, these highly skilled developers create lousy software. There are considerable difficulties in merging the different pieces of code, and adding new features constantly breaks production. Other symptoms might be significant difficulties in testing and endless amounts of mocks.
Overall, the practices seem all over the place and code quality is low. The team has to do a lot of extra work to make even the simplest changes. In brief, the architecture is bad.
The problems
The guru
Is your architect a programming genius but they are unwilling or unable to share their knowledge? Maybe they don’t trust the developers enough?
Having just one person responsible for the architecture is a fundamental flaw. Ideally, all teammates should know the architecture well enough to develop it further. The essential minimum is the ability to design each piece of software to fit the bigger picture. If your architect hoards the necessary information, things need to change.
410: Architect Gone
Even worse than having a guru is having no architect at all. Surprisingly often no one knows how the architecture should work. This might be a side-effect of a business decision. Perhaps the product is about to be phased out, or it is not a top priority.
What if the project is critical but lacks an architect? These situations happen a lot of times when the project is inadequately planned. Perhaps the team was founded to fix one problem but has since been expanded and given new responsibilities. Maybe it never popped into anyone’s mind to think about the big picture.
The ideal situation would be to have a person responsible for the architecture of each individual code repository. This means an owner of the code who has the final responsibility for the architectural practices and quality of the code. It can be a new addition to the team or someone inside the team gets a new role.
408: Request timeout
There is a dreadful in-between of having an architect and not having one. By this, we mean the situations where your architect is unreachable. They exist, and they will be glad to share the information you need. However, reaching your architect is a painstaking process. When getting an answer takes days or weeks, people stop asking.
Usually, this happens when the architect has too much responsibility for one person. They would like to help their colleagues but simply don’t have the time. Perhaps the responsibility has increased gradually during the years they have worked there. The project has grown in scope, but there are no more architects than in the beginning.
Ideally, the architect could review all the merge/pull requests. This way, they can make sure the architectural practices are followed. However, this is not realistic when project size increases.
406: Architecture not acceptable
In some cases, the architecture is well-communicated and even well-documented. The developers know exactly what they should do. But it is utter nonsense. The architecture is of little use to the developers.
Your architect is a great colleague; you don’t want to be mean to them. But they just don’t design good architecture. They are an adequate project manager, but their understanding of large software systems is lacking. Perhaps they don’t have the required experience? What can you do with this nice but unskilled architect?
As a general guideline, the architect should be an experienced software developer in the software team. They should know the codebase thoroughly and be able to develop it with great professional skill.
The solutions
Talk the talk
Usually, the first thing to do is talk. Raise the issue with the team. Bring forward the cases of code quality and adding new parts to the software. Why does bad architecture hinder your team’s performance? This is not the place to blame anyone, but instead to look for solutions together.
With middle/upper management, it is usually helpful to talk about money. How many hours could be saved? How much faster could new features be implemented? You could bring forward a case where good architectural practices would have saved a lot of work.
What if you are part of middle or upper management? In that case, ask the developers what should be done. They probably have a lot of insight!
Walk the walk
If the issue is mainly the unavailability or skill level of the architect, distributing the information and responsibility will help. It’s also a standard good software development practice. Explain how this will make the architect’s life easier.
Do the developers have any time to remove technical debt or refactor code? You could add a couple of tasks related to this in every sprint.
The sacred texts!
A lot of the issues above can be alleviated with good documentation. Your architect doesn’t have to be present in every meeting or be talkative about their knowledge if they can document their thoughts.
But who documents and what? Let’s assume your code is clean enough to be self-documenting. Let’s also assume you utilise API documentation. The documentation should also be kept as lightweight as possible. This way, documenting things won’t get postponed too often.
The architecture documentation should include:
- The crucial information about the domain and use cases
- The purpose and responsibility of each component
- The dependencies between components
- The most important parts of the software’s structure
- Data models and data flow inside the software
- Info on the services your software relies on
- Add graphs for clarity
- Include some dad jokes for entertainment value
Also, ensure all team members can access and understand the documentation.
Organisation changes
Sometimes, no amount of talking, distribution or documentation will solve the problem. Some organisational changes might be necessary. Perhaps the architect can be relieved of some other tasks, and they could focus more on architecture and merge/pull requests.
In some cases, getting a new architect could be the solution. The usual objection to hiring a new architect is the cost. You must explain why a dedicated architect will save costs in the long run. Ensure the new architect has a technical background and software development skills.
Hiring is not always an option, though. Maybe each smaller team can name one of their developers as their architect? Having the architect work inside the team will make communication way easier. They will be able to make sure the team follows broader architecture practices and fits them into the team codebase.
Just be careful; you might end up responsible for the architecture yourself!
The bigger fish
Often, the problem is not an individual architect or a team. The issue of bad architectural practices can be organisation-wide and deep-rooted in its culture. Changing one team’s work methods won’t fix the bad architecture and methods seeping in from other parts of the company.
Trying to change the whole organisation is incredibly difficult and a job for the upper management. But you can still have a positive impact. Changing your team’s workflow for the better will ease your life significantly. And you can use the experience as a case example if you want to bring the issue up with your supervisors. There is always a chance that they will listen.
Am I the problem?
If you are the architect, you might be reading this text with increasing horror. Am I unreachable or technically inadequate? There are some telltale signs which show that there is something wrong with the architecture responsibility setup. Look out for these:
1. You feel there is insufficient time to answer your teammates’ questions.
The developers try to ask you about the different solutions, but you are in a meeting all day. You have 30 emails waiting to be answered, and you don’t even want to open Slack. You are unreachable.
2. No one talks about the architecture.
No one discusses it, so it must be okay, right? There are two possible reasons for this situation: no one has thought about architecture, or the devs have become cynical about it. Seems like you have to start the discussion.
3. No one voices their opinions on the architecture.
Your discussion about architecture is met with quiet, somewhat accepting murmurs. The developers don’t voice their opinions, but clearly, they don’t follow the architecture. Maybe they weren’t listened to in the past? Bad news: you might be the uncommunicative and stubborn guru.
4. People don’t follow the architecture.
Many possible explanations exist: the architecture is bad, or people don’t know its conventions. Or no one is supervising whether the architecture is implemented. Find out your situation by asking your team questions about the architecture. Do they have suggestions to make it better? Or is the subject new to them? Ask, listen, communicate and distribute.
