A review connects a specific question with a traceable investigation and justified next steps.
At a glance
- Four review approaches answer different questions about software. A fictional order management system makes their differences concrete.
- Each example explains what people examine, what they might find and what they produce as a result.
- A selection guide and a short preparation checklist help you apply the ideas to your own situation.
The order management system works. Every day, it creates quotes, calculates prices and processes orders. Yet a new pricing rule now requires changes in several places. Another sales channel needs to connect to the system. Next year, the software will have to handle many more orders at once.
The team has some practical questions. Can the current architecture meet these requirements? Where should we invest first? Would a focused improvement be enough, or should we redistribute responsibilities between larger parts of the software?
An architecture review examines how well the structure of the software supports these requirements. Participants describe specific usage or change situations, called scenarios, and examine the architectural decisions involved.
What will the system need to do?
Architecture determines which software components perform which tasks and how they work together. A review examines the consequences of these decisions for operation and further development.
Participants first agree on the most important requirements. Those priorities determine which parts of the system and which processing steps need closer examination.
The quality of an architecture becomes visible in how well the system meets its requirements and how much effort necessary changes require.
One system, several questions
Our example is a fictional application that has evolved over several years. Order management and pricing are its central components: parts of the software with distinct responsibilities. They exchange information with warehouse and billing systems through interfaces. An interface defines what a request must contain and how the receiving system responds, for example when checking stock availability.
One sales channel already submits orders. A second channel is planned.
Examining architecture, design and code
Several connected questions help us examine this system:
- Responsibility boundaries: Which component performs which task? Pricing applies pricing rules; order management records and processes orders. We check whether the code follows that allocation.
- Dependencies: Which other component does order management need to complete a task? It relies on pricing to determine a price. Changes to pricing may therefore affect order management.
- Data flows: What information moves between components? Order management sends order data to billing.
- Communication: How does that exchange happen? When checking stock, does order management wait for a response from the warehouse, or can it continue processing?
- Quality goals: How well should the system perform its tasks? It might need to keep accepting orders during a warehouse outage. The team defines the conditions and required duration.
These questions apply to both existing software and a proposed architecture.
A design review examines a more detailed design, such as a proposed interface. Developers check whether they can use it to complete their tasks and identify missing information.
Code analysis examines the implementation. It can reveal mutual dependencies or duplicated code. Version history, the record of changes to the code, provides another source of evidence: which parts have frequently changed together? This can help explain why changes require considerable effort.
Four approaches and what you do with them
The following examples explain the questions each approach addresses, the investigation involved and the results participants obtain.
SAAM: How easily can the system change?
The Software Architecture Analysis Method, or SAAM, examines an architecture through concrete scenarios. For our order management system, we follow proposed changes through the components and estimate the effort involved.
What does the team do? It first describes the software's tasks and how they are distributed across components. It then selects important change requests and examines them individually:
- Describe the change. A new customer category needs its own discount rule.
- Identify affected components. The team checks whether pricing configuration can support the rule. Where changes are necessary, it records the affected components and interfaces and estimates the effort.
- Compare further changes. The team then examines a request such as temporary promotional prices. Do both changes affect the same components? Does that match their responsibilities, or suggest that pricing logic is distributed awkwardly?
What might the team find? The new discount rule requires changes in both pricing and order management. That gives the team a specific reason to examine where pricing logic is actually implemented.
What is the result? An overview of the scenarios examined: what the architecture already supports, which changes would be necessary and where change effort is concentrated. Using the same scenarios also makes it possible to compare architectural alternatives.
ATAM: How do quality goals affect each other?
The Architecture Tradeoff Analysis Method, or ATAM, examines how architectural decisions support important quality goals and what risks or conflicts between goals arise.
What do participants do? Business representatives, developers and operations staff explain the business goals and architecture. Together with the evaluation team, they describe and prioritise specific scenarios. The evaluation team then examines the relevant processing steps, recording the expected behaviour and its assumptions, such as the warehouse system's response time.
How does that work in our example? The warehouse integration sometimes responds slowly. Participants set an illustrative goal: an order should be accepted within two seconds. A firm delivery commitment requires current stock information.
Using a description of the processing steps, they follow an order from entry to the stock check. Which steps wait for the warehouse? When does the request time out? What happens to the order afterwards?
A possible finding: The described process waits up to five seconds for the warehouse before saving the order. A slow warehouse response therefore conflicts with the two-second goal. A shorter wait improves response time, but the stock check may still be pending when the order is accepted.
This conflict is a trade-off. The waiting time is also a sensitivity point, because changing it strongly affects response time.
What follows? The evaluation team documents the risk, the affected quality goal and the assumptions about the process. One option to investigate is accepting the order with a “Stock check pending” status and adding a delivery commitment after the check succeeds.
Business representatives clarify whether that process is acceptable. The team can then test the chosen solution with many simultaneous orders and delayed warehouse responses. The review records why a change is worth considering and what needs clarification before implementation.
ARID: Can developers work with the proposed design?
Active Reviews for Intermediate Designs, or ARID, examines more detailed partial designs while they are being developed. Future users of the design, here developers of other components, try to use it for selected tasks.
What do participants do? The design owners present the proposed interface. Developers collect and prioritise tasks they need to perform with it. They then work through the necessary calls and processing steps together, for example in pseudocode: a simplified description of program behaviour.
In our example, the new sales channel needs to create an order. After a connection failure, it sends the same order again. Developers work through this case using the proposed interface:
- Which identifier uniquely identifies the order?
- How do they learn whether the first attempt succeeded?
- How does the proposed process prevent a duplicate order?
A possible finding: The interface lacks a unique order identifier. Developers therefore lack a necessary detail for handling a repeated submission safely.
What is the result? A documented list of difficulties encountered while using the design, such as missing information, unclear error responses or conflicting expectations. The design owners receive specific input for revision before more developers start using the interface.
LASR: Which risks need closer investigation?
The Lightweight Approach for Software Reviews, or LASR, helps a team assess software together and decide which risks deserve closer examination.
What does the team do? It briefly describes who uses the software and for which tasks. It then agrees on important evaluation criteria and compares the desired properties with its assessment of the current system. Participants explain their assessments, collect risks and investigate relevant or disputed points in more detail.
How does that work in our example? The team agrees on a criterion for ease of change: a new discount rule should require a manageable amount of effort, while existing rules continue to work correctly. It defines acceptable effort and test cases for both new and existing rules.
Developers and business users first assess how well this works today. To resolve differing assessments, they examine a recently implemented discount change. SAAM followed proposed changes through the components; here, the team investigates a rule that has already been introduced. Which files changed? Which tests ran? What errors were reported afterwards?
A possible finding: The discount threshold changed in pricing. An additional check in order management still used the old value and rejected valid orders. The change record and error report show that the same business rule had to be maintained in two places. This evidence helps explain the different initial assessments.
What follows? The team records the deviation from its criterion and the risk of inconsistent pricing rules. For the rule examined, it recommends maintaining the threshold in pricing and having order management use the result. A test covering both components should check that valid orders are processed correctly.
Whether other rules are also duplicated becomes a focused investigation task. The result is a reasoned assessment of the system, with specific improvements and open questions for further examination.
Which approach fits your question?
| Your question | Approach | Expected result |
|---|---|---|
| What changes would planned requirements need? | SAAM | Affected components, necessary changes and estimated effort |
| How do architectural decisions affect several quality goals? | ATAM | Risks, trade-offs and decisions that strongly affect important properties |
| Can developers complete their tasks with a partial design? | ARID | Specific difficulties and missing details to guide revision |
| How do we assess our system together, and what should we examine more closely? | LASR | A reasoned assessment, identified risks and findings from focused investigations |
This guide helps with the initial choice. Available documentation, participants and the required depth of investigation also shape the review.
Prepare the decision and the evidence
Before starting, clarify five things:
- Decision: What should the review help you decide, such as connecting another sales channel or reorganising pricing logic?
- Requirements: Which situations should the system handle, and under what conditions?
- Participants: Who understands the business requirements, the code and day-to-day operation?
- Material: Which architecture diagrams, interface descriptions, error reports and measurements are available?
- Scope: Which conclusions need support from code inspection, tests or measurements?
What role do analysis tools play?
Analysis tools can show which components call pricing or contain their own pricing rules. The team compares these findings with the intended allocation of responsibilities. That helps explain why a new discount rule requires changes in several places.
Record which parts of the code were examined and which questions need further investigation. A later article in this series will look more closely at selecting and using analysis tools.
Takeaways
- Start with the decision you need to make. Connecting a sales channel and reorganising pricing logic may require different investigations.
- Make requirements concrete. “Accept an order within two seconds” gives the team a clearer basis for examination than “the system should be fast.”
- Connect recommendations to findings. Record what was examined, which assumptions were used and what remains to be tested.
- Consider focused improvements. In our example, the team might retain the component structure, consolidate a duplicated pricing rule and test behaviour during a warehouse outage.
Your next step
Choose an upcoming change or a recurring problem in your software. Write down what the system should do in that situation and which decision the investigation should support. Then use the selection guide to choose an appropriate approach.
For me, this is the practical value of a review: the team can explain why it recommends a change and what improvement it expects. The people responsible can use that reasoning to decide what to implement next.
Coming next in the series
This article opens the series “Examining Software Architecture in Practice.” The next articles explore the four review approaches in more detail using our fictional order management system. We will then examine what code analysis tools can reveal and how findings lead to concrete improvements.
Next up is SAAM: we will follow a new pricing rule through the software and record which components would need to change and what effort that involves.