As a software architect, you have engineered and designed a wonderful architecture. The architecture meets functional as well as quality requirements and is now ready to be implemented.

One particularly difficult problem you will be facing is to ensure the code written by the developers actually implements the defined architecture. Don’t get me wrong here, we don’t want to blame the developers. Of course they have seen and read the architecture, but still, experience shows that divergence will happen. It might have been a tight deadline. Or it has been some while ago that developers actually looked at the architecture. Maybe they even understood you wrong while you explained the intended architecture.

Keeping the code aligned with the software architecture is an ongoing process and as a software architect, you need to take care of it. This article will show you 12 simple ways you can use to keep the implemented architecture consistent with the planned architecture.

Technical Architecture Evaluation

The first dimension in ensuring your implementation aligns with your architecture is to setup some technical tools that guide developers and help you inspecting the state of the implementation.

Static Code Analysis

At a very basic level static code analysis helps to be formatted according to some agreed coding styles. Static code analysis is simple to setup and greatly improves the maintainability of the code by enforcing that code looks similar regardless of which author has written it.

Static code analysis can also find bad practice and code smells through tools such as SpotBugs. Adding such a tool not only reduces the number of bugs in the code, but can also improve the security or performance.

As an architect, the most important static code analysis tool extracts meaningful quality metrics of the source code and can pinpoint potential problems. These metrics can also be used to pinpoint architectural violations in the source code. Ideally, the static code analysis tools is integrated into the CI/CD pipeline and generates interactive reports for you to explore (view the demo of PhpMetrics as a great example).

Automatically Test Your Architecture Rules

Yes, the headline is not promising too much: you can indeed formalize and automatically validate architectural rules! For Java, you may have a look at the ArchUnit project, which has a nifty API to express architecture rules as unit tests. For example, lets verify that services don’t access controllers with this simple unit test:

    @Test
    public void services_should_not_access_controllers() {
        noClasses().that().resideInAPackage("..service..")
                .should().accessClassesThat().resideInAPackage("..controller..")
                .check(classes);
    }

With the help of such a tool, you can really formalize lots of architectural rules and patterns and automatically test them against the real code. For JavaScript / TypeScript you can use dependency-cruiser.

Architecture Decision Records

Of course you documented big architectural decisions in your architecture documentation, but architectural decisions are also made on a small scale. If the architecture documentation does not overspecify everything, developers still need to make architectural choices and decisions (which is good!).

To ensure these architectural choices are not lost, they can be stored as architecture decision records (ADRs) right next to the source code. ADRs are light-weight markdown based documentation files without enforcing too much structure. Once an architectural discussion has been carried out, the decision of that discussion as long with any consequences should be stored in an ADR.

ADRs have a high value in the future when looking at the code and figuring out why things were implemented as they were. Maybe functional or quality requirements have changed and the decision today would be different than what it was at the time. By documenting the decision we can leverage that documentation in the future to decide whether there is a need to change the code (or that we better leave it as is).

Reviewing the Implemented Architecture

Besides the technical measures an architect can take to keep the implementation aligned with the architecture, there are also several ways to iterate together with the developers. By reviewing, feedback will automatically transfer knowledge and is a win-win situation for all participants.

Code Reviews

As an architect, you can also do code reviews in the form of a pull/merge request review. Please do keep a special eye on architectural considerations and concepts and whether they are properly implemented.

No single line of code should get into the master branch without a code review. If code reviews are not how your team works, establish a culture of positive and constructive feedback in code reviews. It is important that developers like this tool and do not see it as a burden.

If your team gets used to kind of feedback they get from you as an architect you can also empower the team to identify critical merge requests themselves and assign you as a reviewer. By doing so, you still can give highly valuable input to your team, but you are not involved in every pull request. Oh, and if they do want your feedback on a pull request, make sure to provide it within 8 hours. No one likes to wait forever for PRs to be reviewed.

Retrospectives

Retrospectives are a great way to assess potential problems in your team and take action to minimize those problems. As an architect, you should attend the retrospective and listen to your developers to hear what they are struggling with. By listening to the retrospective you get a good impression of the state of the team and the general mood.

Chances are, developers are struggling with something that is in your circle of influence. For example, you could improve tight deadlines due to wrong estimations by assessing the risk of your architecture missing critical aspects of the application. Without talking to the developers you will never realize that there might be a problem. The retrospective is a great meeting to attend, as it is focused on continuous improvement and developers openly raise concerns if they have some.

Time-boxed Quality Assessment

Either alone or with developers you can setup a time-boxed quality assessment of the team’s most recent source code (i.e. last 1-2 sprints). If you haven’t done this before, start with your team and a time-slot of half an hour. It is very important that no blame game is being played here - no one should ever point out who the author was. Not during the meeting and not afterwards. It is important that everyone knows and agrees to this rule.

During the assessment you compare the architecture documentation with the actual implementation. This includes documented architecture components, their interrelationships and constrains, but also defined architectural concepts such as security concepts. If doing this with your team make sure to ask if there is a particular reason for a deviation (maybe there is!). And if there is a deviation, make sure to either update the architecture or update the code.

Next to that, you can keep your eyes open for great solutions to a problem. Maybe the solution is better than that defined in the architecture or the solution is not documented in the architecture at all. After consideration and evaluation of the solutions’ suitability for other contexts you can add the found solution to the architecture.

Code of the Week

“Code of the Week” is an idea that I’ve heard for the first time by Gernot Starke. The “Code of the Week” is a time-boxed meeting (0.5-1 hour) where developers bring pieces of code they want to talk about. Again, the idea here is not to play a blame game and it is important that everyone focuses on the code and no one ever talks about the respective authors.

Developers are invited to bring fantastic or awkward code, even from places where they have not done anything. The team (and architect) should discuss the code, the reason it might be there and if needed, what options there are to change it.

This methodology fosters interest in the architecture and good code and improves bad places in the code base over time. It also creates a shared understanding of what good and bad code is and how code aligns with the architecture.

Participate

Next to reviewing things that have already been done an architect can also proactively participate in the development process to make sure the code aligns with the architecture.

Pair Programming

Pair with a developer, it is that simple! By pairing, you coach and transfer your knowledge about the architecture to your team members. Pairing is also very effective for critical parts of your application.

You could also setup a half-day pair programming session on a regular basis with your team. Members should rotate, of course, but doing activities on a regular basis ensures you do them at all. Going even further you could try mob programming to get your whole team involved.

The discussions around the implementation help to align the code to the architecture. More important, this greatly helps in shaping a common understanding of the architecture and its concepts.

Architect as Part of the Development Team

Ideally, the software architect is also part of the development team and actively spends time developing the application. By being part of the team you can steer and make architectural decisions aligned to the overall architecture.

However, more valuable than your actual contributions to the code base are your insights and reasons for doing things in a particular way. Make sure you always communicate the big ideas and concepts of your architecture to the team - as part of the team you get to spend a lot of time with the team which is an ideal basis to nurture the architectural understanding in every team member.

If you have a larger organization you could also be part of a team every now and then, or even be part of new teams and then fade out after a while. Talk to the developers what they find helpful and useful. I’m fairly certain that you have enough things to do even if you don’t code.

Informal Communication

Talk to your team! Build a deeper connection! Use that moment at the coffee machine to ask people how they are going and what they were up to last weekend. Sincere small talk establishes a level of trust between you and all team members.

If trust is established people will naturally open up and seek your advice in case of difficulties or questions. Make sure team members are not afraid to approach you for any question they might have, even if the question is easy to answer. Help your team members do a great job and you will see that by having a close connection to all team members you have a lot of influence on day-to-day decisions which sum up to help keep the code aligned with the software architecture.

Participate in Stand-up Meetings

Your team meets every day to discuss what they are working at. Go and join them. You will learn about impediments they have and potentially about struggles while implementing certain features.

Just as with most of the other participate methods choose which teams’ stand-up meeting to join and how often you want to join. It is important that you stay in contact with the developers and to signal to them that you are available at their disposal.

Architecture Coaching and Workshops

If you feel there is a lack of knowledge for particular team members or topics then go ahead and coach them. You can also organize a workshop to talk about the subject of matter.

A common theme is that communication is key to align developers with your architecture vision. Coaching and workshops are very intense forms of communication to be effective, so always evaluate whether they are a good way to address the issue you have identified.

If you do organize a workshop or training you most certainly put slides together. If the presentation is short enough you can record it and make it available in your internal project wiki. That way, any new team members can benefit from the workshop as well as they can have a look at the online resources. If you’re not into videos then at least upload the slides and make sure to design your slides that one can follow the general idea without hearing you talking.

Conclusion

There are so many ways a software architect can help developers build an implementation that is congruent to the software architecture. Of course you can’t do everything so choose some that work in your particular situation. And adjust if required.

Especially the technical measures are easy to setup and require an up-front time investment. When dealing with software architectures, it is very very important to communicate about the architecture in order to create a shared understanding of the architecture and its concepts. What actions are you taking to ensure the code aligns with your architecture?