What defines software design? Good software design is easy to change.

This is a widely accepted concept, as we can see in the following quotes:

“Refactoring improves the design. What is the business case of good design? To me, it’s that you can make changes to the software more easily in the future.” — Martin Fowler Ref

“Good Design Is Easier to Change Than Bad Design.” — The Pragmatic Programmer Ref

Therefore, to be a good architect, one must make things easier to change over time.

1. Learn to design change. Designing is not only about creating new things

Ninety-nine percent of what you do as an architect is designing change. Get used to learning existing architectures and seeing the emerging design. Most of your career will be about changing existing software. If you fail to learn the existing architecture or fail to recognize the design that emerges from existing projects, you’ll likely become the “let’s rewrite” person.

“Any organization that designs a system (defined broadly) will produce a design whose structure is a copy of the organization’s communication structure.” — Fowler

2. Avoid revolutions (No rewrites)

Revolutions may result in a better future, but frequently the revolutionary dies

By definition, rewrites are very risky. I like to call them revolutions. What you’re asking your organization or customer is to spend a lot of time, money, and energy to end up, months later, in roughly the same place and hopefully better. Revolutions sometimes result in a better future, but frequently the revolutionary dies in the process.

For that reason, rewrites must be avoided unless they are absolutely necessary. Small, continuous improvements are much better. The new always shines, and in the computer field there will always be new things fighting for a stake in the market. They will try to get your attention, read about them, run POCs, but don’t try to follow every new trend, which would inevitably lead to never-ending projects.

Assume that the person who wrote the old code might have known something you don’t

Jordan Peterson: “ASSUME THAT THE PERSON YOU ARE LISTENING TO MIGHT KNOW SOMETHING YOU DON’T.”

When writing the code that today is called legacy code, the person who wrote it had something in mind, and often this information is lost in the process. If you look at ugly code with arrogance, you will miss the opportunity to learn from it. Sometimes you’ll be lucky and they will still be around so you can talk to them and learn the reasons behind the code and why it was done the way it was. But most of the time, you have to act like an archaeologist and rebuild the context in which the code was created by looking at the final code and the commit history.

Don’t get me wrong: rewrites are necessary sometimes. I have led some big rewrites in my career as an architect; they often help solve problems the team is facing with the old codebase. On the other hand, most of the time they bring back old problems that the team didn’t even remember they had solved before; or the people who solved them are no longer around to explain why they did what they did.

In the book Built to Last, the authors have a chapter dedicated to the concept of “Preserve the core, stimulate progress.” This does not mean the team won’t make significant changes or try new solutions; rather, it means preserving what is well established and innovating around the core. Eventually, everything may change, but that should be the result of continuous progress rather than sudden, drastic revolutions.

Martin Fowler has an entire book on refactoring if you don’t feel comfortable changing a massive amount of code.

There are methods to change existing code and great references that would require more space than I can dedicate in this blog post. But if you are afraid of changing legacy code, you are most likely living in the “Edit and Pray” mode. You must change the mode to “Cover and Modify,” which is the correct way to deal with changing code. This is a reference to the book Working Effectively with Legacy Code, and I also talk about it in this very blog in the post How not to burn out when working on hard problems as a developer.

3. Code often and well (Code well)

Take on at least one coding task during each iteration (sprint, month, release, etc.). This is the only way to keep your skills sharp, understand the code, and ensure the things you are designing will fit well in the already running code.

Set an example for the other engineers by demonstrating the standards you want to uphold when writing code. Even the best design will fail if the implementation is a disaster.

4. Sync frequently (Biweekly Architectural Review)

Open a regular forum for people to bring design challenges. I run this every other week, and any person on the team can call an emergency meeting at any time if something has to be designed in advance.

At most, once every other week, run a meeting specifically to talk about architectural decisions and open space for people to bring architectural problems.

5. Document decisions (ADR)

“The only thing worse than failure is passing by accident.” Ref

If you have been in a car accident, you know that when we make mistakes, we tend to rethink everything that happened, every second, and how we could have prevented it. We rarely, or never, do the same when we have success, and there are lessons to be learned in both cases. Documenting your decisions is crucial to evaluate why a plan did or did not work.

ADR — Architectural Decision Records

This is one of the most important points: use ADRs so future architects/developers working on your codebase understand the context in which decisions were made and what trade-offs you considered when they were made. As important as documenting what decision you took is documenting the context and what problems you foresaw and are willing to deal with the consequences that may come.

Every hard decision is controversial; otherwise it would be trivial and wouldn’t even be a decision. Therefore, it is important to document the controversy and why you took the decision you took.

ADRs are a simple yet powerful way to document decisions, with a template to capture the context, consequences, and alternative directions considered.

6. Use more than one architectural framework (Architecture style is not a religion)

I know many architects who focus on only one source for architectural style. Having only one tool for all problems rarely yields amazing solutions. To be a good architect, one must know more than one architectural framework.

• Hexagonal Architecture
• Clean Architecture
• Microservices architecture
• iDesign
• Event-Driven Architecture
• Microkernel Architecture
• etc.

Do not let architectural style become your religion. Read all of them, take the good parts, choose one that is close to your problems, and apply them in different contexts so you can learn where they fit and where they won’t.

7. Read and Write (Book club and internal blog, personal blog, notes)

Read the library documentation, good books (also the ones you don’t love but are well respected in the field), and argue from references and evidence.

Know the basics (Or at least have a good understanding of what they mean)

For each topic, I will provide a reference. Please do not feel obligated to read them all from beginning to end, and also do not limit yourself to the list I am providing here. Seek out other sources that will enhance your knowledge. (Check the reference links, some of them are old reads)

• Distributed systems Ref
• Design patterns Ref
• Database theory Ref
• Network theory Ref
• Formal verification Ref
• Automata theory Ref

Knowing the basics will help you to evaluate any technology, even if it is brand new and the problem it is trying to solve is not yet clear. For example, a web developer can still perform well without knowing much about TCP/IP or any other network theory or protocol. However, if they do know it, many problems can be avoided, such as preferring one request to bring more information rather than many requests bringing a small amount of information.

Notes

• Take notes and share them with the team. (I have way too many posts about this, check out the other posts about notes for more details)

8. Keep an eye on the future (Tech radar)

Research, experiment, and drive the future of the tech in your company. Things move fast and you, as the architect, have the responsibility to ensure the team and the company take advantage of new technologies that emerge in the market. That does not mean you need to rewrite your frontend in every framework that is released every other month (re-read my first rule if you need).

At leas once an year update the company’s tech radar, TW has a great template you can follow Tech radar example

9. Don’t take yourself too seriously (Be humble)

Interesting ideas come from everyone; even the most junior engineers on the team can bring the most interesting ideas. In fact, innovations often come from newcomers. Don’t get me wrong, specialists will have a view of the problems already documented in the literature and academia, but a new person may bring a perspective that by not limiting their imagination may lead to great solutions.

Listen to everyone’s ideas carefully, assess them, challenge them, and let them take shape no matter who they come from. Decide, document the decision, and move on.

10. (Bonus) Experiment

It takes time to become an architect, and it is not easy to train new architects. It may take years of formal training to get the academic background needed, and after that a couple of years experimenting in small and medium-size projects.

I struggle to see how any person could become a good architect without designing at least a handful of systems or making significant changes in big systems and dealing with the consequences of those decisions for at least five years.

That is why, when mentoring, I advise creating personal projects with paid users. This allows individuals to see how small problems progress and grow over time. Often, the trade-offs only prove to be good or bad after years. Sometimes this happens only after a new tech cycle (such as frameworks becoming obsolete or technological disruptions). Moreover, if you only design for your job, you may not be there to see all the consequences of your decisions.

Closing thoughts

This post focuses on the non-obvious things you need to do to become a great architect. Every architecture book will teach you how to design greenfield systems, and it’s not hard to find architects who don’t code (or even look at code) for years; in my opinion, that’s a clear mistake.

Use this as a guide for your journey. If you’re junior or just starting your career, don’t obsess over every detail. Take what you can remember, apply it, and come back in a few months or years to revisit what your next step could be.