Efficient Software Architecture

Defining and keeping an efficient Software Architecture is a hard job, not only due to the complexity of the system but, more frequently, to the challenges related to making people agreeing on something and follow some basic directions and rules.

• Common Issues in Software Architecture
  • Reason 1: Your way of working does not work
    • No process at all
    • Fake “Agile” Architecture Process
    • Heavy (and boring) process
  • Reason 2: You keep repeating “boilerplate tasks”
  • Reason 3: You don’t have a good decision-making mechanism
• The Practical Architecture Process
• The Process Stigma: sounds boring

The keys to success are getting a good consensus without spending too much time in discussions, documenting what you want to achieve in a maintainable manner, and being able to execute what you planned. This blog series helps you with these topics, by defining a simple process you can follow on a daily basis.

Common Issues in Software Architecture

Let’s cover what I consider the three most important reasons.

Reason 1: Your way of working does not work

In this case, your daily activities intended to achieve an efficient Software Architecture don’t work. There might be a few reasons for that.

No process at all

Clear evidence of this is when there is scarce knowledge in your organization about how your software is structured, how it behaves and where you want to go with it. Another potential symptom of not counting with a good process is having a Meeting-Only Software Architect, that only participates in the software creation process with design meetings, which outcome does not include an action plan and which contents are normally forgotten in a week. A third possibility is having Reactive Software Architects that are only summoned when there are problems, and then it’s usually too late.

Even though the Software Architects may have a perfect picture of the entire architecture landscape in their minds, for the developers there is a feeling of chaos and the odds are that you deviate from the decisions and conventions very often.

Fake “Agile” Architecture Process

This is a vague term, but here I use it to define the situation of not having any process at all and pretending that it’s the best way to go since your company is Agile.

In this scenario, you often hear things like “the code is our documentation” and “we don’t do diagrams since they become obsolete very soon”. Same as the first case, this strategy might work for small teams when combined with very good communication between its members but, as the team grows, discrepancies and the fact that there are no rules nor conventions may introduce a lot of noise in the daily work.

Heavy (and boring) process

On the other side, there are also situations in which the architects are trapped inside an endless Architecture Process in which everything the team does has to be paired to a formal document, no matter if it’s UML, plain text or even a proprietary format. The problem here is twofold:

• The documentation produced and the process itself are seen as a set of forced steps required to continue working on the project, so people may come up with a way to cheat the system and do the bare minimum to satisfy the organization. Normally, that ends up with useless documentation for humans.
• The process generates so much output (too verbose) that the developers either don't have time to read the docs or experience Information Overload: they have so much information that it's actually harder to understand the foundations and to make decisions about the system (see Information Overload).

As you can see, this is yet another example that extremes are wrong: you can find problems with and without a Software Architecture process. What I aim to achieve with this book is that you find a sweet spot in between: you can configure your own lightweight Process, try it, and adapt it until it works for you.

Reason 2: You keep repeating “boilerplate tasks”

In Software Architecture, a good process can help us remove all the extra effort required for repetitive tasks such as:

• Where do I place this design document? What should I include there? Which tools do I have?
• How many tests does this code require? Do I need to document it? Who do I need to ask to include this extra library?
• Who should I invite for a design meeting? Do we really need a meeting? What should I include on the agenda?
• I have a problem to solve in code that looks like a boilerplate task, do we have conventions to solve it? Can I reuse a common pattern?

Sometimes we don’t notice how much time takes, as a whole group, thinking about this kind of questions. However, when you agree on these basic rules and patterns, you can focus on real, creative and fulfilling work. The reasons are simple:

• Everybody knows where to find the outcome from previous actions (e.g. docs), and they can reuse it.
• You avoid endless, recurrent discussions about trivial topics (see next section about making decisions).
• Since everything is organized the same way, you don't need to look into multiple places or ask multiple people to find what you're looking for.

Reason 3: You don’t have a good decision-making mechanism

I’ve seen many times teams that struggle to make decisions related to their Software Architecture. Other teams make decisions very fast, but nobody follows them later. There is no single reason behind those problems, it’s like a cocktail with several possible ingredients:

• The Dictator. Only one person makes the decisions without consulting others. In this case, it doesn't matter if the outcome is documented or not. It's unlikely that the decisions are good since they're never taking into account multiple perspectives. Besides, the team won't feel represented so they won't embrace those decisions. The result is a team that is either feeling frustrated for following rules that they don't understand or skipping the rules because they feel the decisions don't make sense.
• The Decision Queue with multiple Workers. The first person who faces a common problem defines the common solution. This is a variation of the first one with same results. If that person is not taking into account other requirements by involving others, the decisions won't be good.
• The Déjà vu. With this one, we enter into the world of making decisions involving a group of people. The déjà vu happens when you come back to problems that you've seen before, and you're making decisions about a specific topic that was already discussed in the past. There are two variations of the déjà vu:
  • You discussed the problem in the past but you never made a decision on how to solve it. Normally, this is manifested as a series of meetings that go nowhere, in which the attendees tend to focus too much on how bad the problem is, but not on thinking of possible solutions and defining actions.
  • You discussed the problem in the past, and you made a decision, but there you are again… It might be caused by a badly documented decision or bad communication (a decision was made but nobody knows it). The reason can also be that some people don't like the decision and would like more time to argue about that.
• The Tabs vs. Spaces fights. Trivial discussions are devouring your working time. You enter a meeting with the goal of making a decision that is important for the project but somehow you end up consuming most of the time in topics that are minor and should be decided quickly (they can be easily changed later and/or there is no clear preference for one option). Some of these trivial topics, micro-problems attacking your meetings, may also be recurrent (let's call them micro déjà vu's).

Having a good process in place will help you deal with these situations and come up with productive outcomes. Surely it won’t remove these issues from the working environment since they just happen to be part of software development, but a pragmatic process can make a big difference.

The Practical Architecture Process

Having good ways of working for Software Architecture saves you a lot of time, and helps build the foundations of a successful Software Project. But, how to set up a process that is at the same time efficient, easy to adopt and implement and compatible with Agile methodologies? That’s what you’ll learn with this book.

First, let’s start with the basics: what is a process?

A process is a set of recurrent or periodic activities that interact to produce a result. Wikipedia: Process

A process for SW Architecture

How does that definition apply to Software Architecture? That depends on how we define result. In most organizations, the results they expect from Software Architects are:

• Software that is flexible, scalable, modular, fast, etc. The specific list of System Quality Attributes for your project may of course vary.
• A Vision, that shows the long-term technical shape of the project.
• Experience in applying patterns and techniques to solve problems.
• Coaching others, so the knowledge is spread among the team members.
• Creating, and especially helping others create, new ideas that may provide competitive differentiation to the project.

The better an Architect is at doing those tasks, the better the produced Software Architecture of the project is. Therefore, the goal of Software Architects is to perform those tasks as good as we can.

Note that the documents that compose an Architecture Guide are not included in the list of expected results. You will see this remark a few times along the book: documentation is not a goal, it’s just an instrument to achieve the goals. The Architecture Documentation is a set of generated artifacts from your daily activities. Given that it’s one of the most important instruments you have, this book will teach you how to produce this documentation and how to structure it.

So, how to get there? Can we come up with a set of activities to produce these results and achieve our goals? That’s the Software Architecture Process, and this book helps you set up your own one based on a series of steps.

As a difference from an industrial process, you can’t manufacture Software Architecture. The purpose here is different. The steps in this book help you focus on the creative side and forget about all the boilerplate tasks: meeting structure, preparation, agenda, input and output documents, etc.

The Practical Architecture Process

The Process Stigma: sounds boring

The word process may trigger a negative feeling. It’s normal: many of us have suffered from extremely boring tasks that were required during the normal software development process.

In the past, I’ve been required to fill in a document of about ten pages each time we wanted to include a new library as a dependency in our Java project. Even a popular one, such as Guava or Apache Commons Lang. It could take almost one day to fill in the document, plus a few weeks for the document administration to finish. Say four weeks are required before you can use that useful method that will save you write 200 extra lines of code. If you’re under pressure, you’ll forget about the library and put those extra lines in your code, paying a higher price in maintenance and code crappiness. In this case, the process is not only boring but annoying and counter-productive.

You don’t need an ISO norm, going too formal or hiring extra people to implement a process. All you need is a Git repository or a wiki-style platform where you can write the steps to follow to achieve something or the decisions you’ve been making over time. And, as you’ll see in the next sections, you can create a lightweight process, tailored to your needs and easy to maintain and follow.

A good process is like a good recipe. Maybe you copied that recipe from a website and it’s too detailed and it takes too long to read. Maybe you don’t like spices so you remove them from the process. Then, you modify the recipe and make a list of steps that work for you, that makes you achieve that dish that you love: a great outcome. After some time, you don’t even need to follow the recipe because you know it by heart. But you got there by taking notes and fixing the process, and that’s much more efficient than improvising the steps each time you prepare the dish and trying to remember them the next time.

Continue to The Process Overview and learn how you can use meetings and lightweight docs for better organization.