![\"\"](\"https:\/\/simpleprogrammer.com\/wp-content\/uploads\/2018\/09\/architecture-square-300x300.png\")
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\u2019re building.<\/p>\nEvery 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\u2019re building.<\/p>\n
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.<\/p>\n
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.<\/p>\n
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.<\/p>\n
This way, there\u2019s no danger of becoming an ivory tower architect<\/a> who decides everything for<\/em> the team but who is not respected by<\/em> the team. You want the team to participate in important decisions, and not feel left behind.<\/p>\n Here\u2019s how I drive architecture decisions in my projects by taking responsibility<\/a> while working with<\/em> the team.<\/p>\n 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:<\/p>\n This list is the repository of architecture issues, and every person on the project should know it. It\u2019s accessible to all and editable by all. Everyone is invited to add their issues and ideas concerning the architecture to this list.<\/p>\n 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\u2019ll get there.<\/p>\n 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\u2019s going to drive the evolution of our software\u2019s architecture.<\/p>\n Don\u2019t 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.<\/p>\n Actually, you should even maintain an architecture issue list if you\u2019re the only person contributing to it or if you\u2019re 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\u2019re afraid you\u2019ll forget something. Or you will actually forget something. Your future self will thank you for everything you write down.<\/p>\n Collecting issues and ideas alone doesn\u2019t cut it, though. We need to talk about them and make decisions based on them in a structured manner.<\/p>\n 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\u2019t 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.<\/p>\n What I\u2019ve successfully done in the past is to establish a community of practice (CoP) for architecture topics. The term \u201ccommunity of practice\u201d is often used in agile projects to describe sub-teams that each drive a certain topic within the project, but it\u00a0originates from even before agile became a buzzword<\/a>.<\/p>\n 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 \u201cactively practicing\u201d part is important because if they\u2019re not developing software, they won\u2019t know the consequences of any architecture decisions.<\/p>\n It\u2019s important to select the issues to discuss before the meeting<\/em>. Otherwise, the meeting will likely degrade into an unproductive mob prioritization session.<\/p>\n 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.<\/p>\n 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.<\/p>\n One point on the agenda should be to go through all items currently \u201cin progress\u201d to follow up on them.<\/p>\n Having decided on something usually feels rather good. No matter if everyone supports the decision or not, we\u2019re making progress.<\/em><\/p>\n This progress must be documented. We must be able to come back in a year and say, \u201cAh, yes, that\u2019s why we\u2019re doing this the way we\u2019re doing it.\u201d<\/p>\n There are few things as frustrating as discussing something and having to say \u201cI remember we talked about this a couple of months ago, but I don\u2019t remember what we decided back then.\u201d<\/p>\n And let me tell you, this happens a lot to me. I have a chronically bad memory (or perhaps a chronically selective one).<\/p>\n Let\u2019s call the documentation of our decision an \u201cArchitecture Decision Record\u201d (ADR). That\u2019s a term that has gained some traction since it was included in ThoughtWorks\u2019 technology radar<\/a> in 2016.<\/p>\n 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):<\/p>\n 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.<\/p>\n 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.<\/p>\n 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.<\/p>\n 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 \u201cWe have talked about this already\u201d works wonders.<\/p>\n 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.<\/p>\n In this case, we still have a couple of options.<\/p>\nCollect Issues and Ideas<\/h2>\n
\n
Establish a Community of Practice<\/h2>\n
![\"\"](\"https:\/\/simpleprogrammer.com\/wp-content\/uploads\/2018\/09\/community-of-practice-300x300.png\")
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\u2019s contributed issues, so I can gain a better understanding of the issues. Then I decide which topics should be part of the meeting agenda.<\/p>\nDocument Your Decisions<\/h2>\n
\n
And When There Is No Consensus?<\/h2>\n
![\"\"](\"https:\/\/simpleprogrammer.com\/wp-content\/uploads\/2018\/09\/team-consensus-300x300.png\")
If the matter is urgent and needs to be decided quickly, we can give in to our debating partner\u2019s opinion and do it his or her way<\/strong>. Even if we think this is not the best way to do things, it might be better to do something<\/em> 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.<\/p>\n