Every type of work needs some structure for things to go smoothly. In software development projects, an important part of this structure is the architecture of the software we’re building.
Architecture describes the building blocks of our software and how they work with each other. If every team member builds the blocks as he or she thinks best, it may work, but it will lead to different styles and concepts used throughout the code base. Chances are that this will quickly lead to unmaintainable code.
If, instead, we have an agreed-upon set of architecture rules, the building blocks will be shaped to fit together and be much easier to extend, test, and maintain.
In my experience as a senior member/architect of a development team, I found it necessary to define a set of architecture rules from the start (yes, even when doing Scrum), but then to get into a mode of continuous decision making together with the team.
This way, there’s no danger of becoming an ivory tower architect who decides everything for the team but who is not respected by the team. You want the team to participate in important decisions, and not feel left behind.
Here’s how I drive architecture decisions in my projects by taking responsibility while working with the team.
Collect Issues and Ideas
First of all, we need a place to collect architecture issues and ideas. This is usually a structured list in form of table with these columns:
- the date the issue was raised
- the name of the person who raised the issue
- a keyword describing the context of the issue in a single word, for ease of indexing
- a short text description of the issue, potentially with links to other material
- the name of the person who will take responsibility for the issue (initially empty)
- a status flag, e.g., “open,” “in progress,” or “done”
This list is the repository of architecture issues, and every person on the project should know it. It’s accessible to all and editable by all. Everyone is invited to add their issues and ideas concerning the architecture to this list.
Usually, not everybody on a team will contribute to this list. Some are content to let others discuss and make decisions, which is totally fine. Often, these are the more junior developers who still lack confidence in their own skills, but they’ll get there.
There are always some developers, however, who will gladly take the chance to contribute ideas about how to do things better and point out the issues they have with the current state of the architecture. Those ideas and issues are what’s going to drive the evolution of our software’s architecture.
Don’t forget to contribute to this list yourself in your role as a senior developer or architect. You want to bring in your experience, after all.
Actually, you should even maintain an architecture issue list if you’re the only person contributing to it or if you’re doing a project on your own. If the list is only in your head, chances are that it will feel like a burden because you’re afraid you’ll forget something. Or you will actually forget something. Your future self will thank you for everything you write down.
Establish a Community of Practice
Collecting issues and ideas alone doesn’t cut it, though. We need to talk about them and make decisions based on them in a structured manner.
In our role as senior developer / architect, we could take the list, withdraw into the penthouse of our ivory tower, and decide on a course of action for each item. However, top-down decisions like that don’t sit well with everyone (and, to be honest, are probably not the best decisions all the time), so we should try to involve the team.
What I’ve successfully done in the past is to establish a community of practice (CoP) for architecture topics. The term “community of practice” is often used in agile projects to describe sub-teams that each drive a certain topic within the project, but it originates from even before agile became a buzzword.
A community of practice in the sense of this article is a group of team members who are interested in software architecture and are actively practicing software development. The “actively practicing” part is important because if they’re not developing software, they won’t know the consequences of any architecture decisions.
Once every two weeks or so, I schedule a meeting for this community of practice. I have a look at the issues and ideas on the list. Usually, a day before the meeting, I talk to everyone who’s contributed issues, so I can gain a better understanding of the issues. Then I decide which topics should be part of the meeting agenda.
It’s important to select the issues to discuss before the meeting. Otherwise, the meeting will likely degrade into an unproductive mob prioritization session.
The meeting is timeboxed, usually not more than an hour or one and a half. Also, each item to discuss is timeboxed so we have a clear-cut agenda.
Each item is then discussed in the group, and if all goes well, a decision is made for the benefit of all. Some items are settled then and there; others may require someone to follow up by evaluating something or talking to some other people. In this case, the item is assigned to a caretaker who follows up. The caretaker and status columns in the issue list are updated accordingly.
One point on the agenda should be to go through all items currently “in progress” to follow up on them.
Having decided on something usually feels rather good. No matter if everyone supports the decision or not, we’re making progress.
Document Your Decisions
This progress must be documented. We must be able to come back in a year and say, “Ah, yes, that’s why we’re doing this the way we’re doing it.”
There are few things as frustrating as discussing something and having to say “I remember we talked about this a couple of months ago, but I don’t remember what we decided back then.”
And let me tell you, this happens a lot to me. I have a chronically bad memory (or perhaps a chronically selective one).
Let’s call the documentation of our decision an “Architecture Decision Record” (ADR). That’s a term that has gained some traction since it was included in ThoughtWorks’ technology radar in 2016.
Essentially, an ADR is a structured document that describes why we have made a decision and what we hope to achieve with it. For example, an ADR may consist of these attributes (adapt this list to your needs as necessary):
- a unique number for easier reference
- a title
- the decision
- the reasons for the decision
- the goals we hope to achieve with it
The ADRs should be kept as close to the code base as possible so that they can be maintained in sync with the code and be part of our code review rituals.
With a well-kept list of ADRs available, we can easily travel back in time when we know we have discussed some topic already and re-evaluate our decision from back then.
Maybe the reasons for a past decision still hold. Sometimes, however, the reasons are not valid anymore because the context has changed or the goals we wanted to achieve with the decision have not been reached. In this case, we can decide on a different way of doing things.
Being able to refer to an ADR also allows us to quickly smother unproductive discussions in our CoP meetings. Just pointing at an ADR and saying “We have talked about this already” works wonders.
And When There Is No Consensus?
There are times when we keep discussing an architecture issue in our CoP meeting and we cannot agree on a course of action for dealing with it.
In this case, we still have a couple of options.
We can postpone the issue to the next meeting. This gives us and the rest of the team some time to think about it. Often, this will be enough to give us or our debating partner some inspiration as to how proceed with the issue. Perhaps we learn something new in the meantime that will help us.
If the matter is urgent and needs to be decided quickly, we can give in to our debating partner’s opinion and do it his or her way. Even if we think this is not the best way to do things, it might be better to do something than to do nothing. Just be sure to document the decision in the ADRs so we can get back to it should it become necessary.
If we really feel that our way is the way to go and disaster will strike if we do it differently, we can overrule the team with our experience. This obviously only works if we are respected enough within the team (or we have a role that gives us the needed authority). And even then, this might offend some people, but sometimes the decision must be made by an architect.
It’s nice if we reach consensus on architecture decisions as a team, but consensus isn’t necessary to successfully work together as a team. If we treat each other with respect while standing strong for some decisions and yielding for others, we can still deliver a well-architected piece of software.
Deliver Great Architecture
Life as an architect or senior developer in a software development team is a lot easier when you involve the team members in the process of making architecture decisions. The team members will feel their opinions are honored, and you spread the architecture knowledge through the team, avoiding architectural messes you would have to clean up later.
The steps of collecting issues, discussing them in a community of practice, and then documenting the decisions take only very little effort, so there’s practically nothing stopping you.
Once this workflow is incorporated into the every-day-life of a project, it will relieve you of the burden of having to decide everything on your own while helping the team to grow and to deliver architecturally sound software.
Start today.
| Published on Java Code Geeks with permission by Tom Hombergs, partner at our JCG program. See the original article here: Architecture Decisions in a Software Development Team Opinions expressed by Java Code Geeks contributors are their own. |
