Software Architecture Issues and Solutions

Software Architecture: Challenges and Solutions

Defining a 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.

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.

This page is part of the guide The Practical Software Architecture:

  1. Software Architecture Issues and Solutions
  2. The Process Overview
  3. Documenting Software Architecture
  4. Vision, Principles, and Constraints
  5. Preparing the Roadmap
  6. Decision Making
  7. Conclusions

Common Issues in Software Architecture

Your way of working does not work

If you’re looking for new ways of doing Software Architecture, it is because probably you come from one of these situations, each with its own problems:

  • No process at all. Which means that there is scarce documentation (or maybe none) 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 doesn’t include an action plan and which contents are normally forgotten in a week. 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 broad concept, 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 a 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, Word or even a proprietary platform. 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 human beings.
    • The process generates so much output (too verbose) that the developers either don’t have time to read the docs or experience Information Overload, not being able to extract any value from them.

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 guide 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.

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:

  • You know where to find the trace of previous actions (e.g. docs), and what is its content.
  • You avoid endless, recurrent discussions about trivial topics (see next section about making decisions).
  • You don’t need to switch context continuously when everything is organized the same way.

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 for 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:
    • 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 the problem 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). But 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’re things that just happen because we’re humans, but a pragmatic process can make a big difference.

A guide to Guiding Software Architecture: The Practical Architect Process

The definition of a process is:

A systematic series of actions directed to some end.

How does that apply to Software Architecture? First, Let’s try to define what is our end.

In most organizations, the goals of having Software Architects are all (or a subset) of these:

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

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

And how to get there? Sometimes we just improvise and react to what’s happening at the current time. But, can we come up with a systematic series of actions so we can focus on the creative part of it and forget about all the boilerplate tasks? That’s what I’m calling here the  Process, and I’ll help you set up your own one based on this reference, The Practical Software Architecture Process.

The Practical Architecture Process

The Process Stigma: is an Architecture Process boring?

The very word process may trigger in you a negative feeling. It’s normal: some people (including me) 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 ~10 pages each time we wanted to include a new library as a dependency in our product (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 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, it’s too detailed and takes too long to read. Maybe you don’t like spices too much so you remove them from the process. So 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.