Let’s start with a simple overview. Like many topics in software architecture, Grady Booch has provided a short and too the point description that explains how to perform an architecture review (Booch2010):
- Identify the forces on the system.
- Grok the system’s essential architecture.
- Generate scenarios that exercise the relevant forces against the architecture.
- Throw the essential architecture against those scenarios, then evaluate how they land relative to the relevant forces.
- Wash, rinse, repeat.
That list of steps is everything you need in a nutshell. Pretty much all other sources of information are just an elaboration of one or more of those steps in varying degrees of formality.
A sidenote: This reference (Booch2010) is to an IEEE Software article. Although IEEE SW is an excellent source of information, it is behind a paywall and therefore it may as well not exist for the vast majority of software architects that I know. Luckily they provide a free podcast where Grady Booch reads the article for you. For all the references mentioned in these blog posts I’ll try to also link publicly accessible sources for further reading (podcast index, mp3).
Where to start?
Let’s begin with a very basic technique: Look at the structure for more detailed reviews, and different aspects concerning context that help you find which parts of a detailed review structure that are necessary for you.
Q: What’s the simplest thing I could do that would be useful
A: Active design reviews
Active Design Reviews (Parnas1985 [pdf]) is one of the original discussions on the topic - and its still excellent. The principles are just as applicable now as they were back then.
Parnas' article begins with a description of how ad-hoc "design reviews" are performed in practice and why this makes it difficult for the review to produce a useful result. I’m going to repeat them here because even though these design review anti-patterns were described back in the 80s I still see them practiced today on large-scale projects with budgets in the order of 50-100M euros.
Events in an ad-hoc design review
Here’s the sequence of events Parnas describes in an ad-hoc review:
- A massive quantity of highly detailed design documentation is delivered to the reviewers three to four weeks before the review.
- The designated reviewers, many of them administrators who are not trained in software development, read as much of the documentation as is possible in the time allowed. Often this is very little.
- During the review, a tutorial presentation of the design is given by the design team. During this presentation, the reviewers ask any questions they feel may help them to understand the design better.
- After the design tutorial, a round-table discussion of the design is held. The result is a list of suggestions for the designers.
- The reviewers are swamped with information, much of which is not necessary to understand the design. Decisions are hidden in a mass of implementation details.
- Most reviewers are not familiar with all of the goals of the design and the constraints placed on it.
- All reviewers may try to look at all of the documentation, with no part of the design receiving a concentrated examination.
- Reviewers who have a vague idea of their responsibilities or the design goals, or who feel intimidated by the review process, can avoid potential embarrassment by saying nothing.
- Detailed discussions of specific design issues become hard to pursue in a large all-encompassing design review meeting
- People who are mainly interested in learning the status of the project, or who are interested in learning about the purpose of the system may turn the review into a tutorial.
- Reviewers are often asked to examine issues beyond their competence.
- There is no systematic review procedure and no prepared set of questions to be asked about the design.
- As a result of unstated assumptions, subtle design errors may be implicit in the design documentation and go unnoticed.
Sound familiar? What I don’t understand is: We were aware of these problems, and how to overcome them, 30+ years ago and yet this still happens in many places. ...but that’s a topic for another rant…
We'll go into details about how to address these problems when we look at more recent techniques.