About aim42

aim 42 supports software evolution, maintenance, migration and improvement - in a systematic and pragmatic way.

aim42 is a collection of practices and patterns to support software evolution, modernization, maintenance, migration and improvement of software systems:


  1. helps you optimize your software and reduce maintenance cost

  2. helps you to identify critical issues, technical debt and risks

  3. supports both business and technical stakeholders

  4. organizes patterns and practices in three phases (Analyze, Evaluate and Improve)

  5. Free and open-source, contributions welcome.

  6. Grounded in practice , proven approaches, backed by serious research.

Authored by the aim42 community, lead by Dr. Gernot Starke <gernot.starke@innoq.com>

0.7.0 /Jul 28. 2016 build-status:unknown nr-of-issues:unknown nr-of-bugs:unknown aim42-github-stars

1. Introduction

1.1. Why is software being changed?

Software systems, at least most of those that are practically used, are changed all the time. Features are added, modified or removed, user interaction is streamlined, performance is tuned, changes to external interfaces or systems are reflected. The reasons for changing a system can be grouped into four categories (see [ISO-14764]):

  • Corrective changes

    • fixing failures within the software system

  • Adaptive changes

    • data structures we rely on have been changed

    • external interfaces have been changed - our system has to cope with these changes

    • some technology, framework or product used within the system is not available any longer and needs to be replaced

  • Perfective changes

    • operational costs have to be reduced

    • maintenance costs have to be reduced

    • existing documentation does not reflect the truth (any more)

    • resource consumption needs to be optimized

    • system needs to work faster

    • system needs to become more reliable or fault-tolerant

    • people need new features

    • system needs to be integrated with new neighbour

    • system needs to comply to new regulations or laws

    • system needs new or improved user interface

    • existing features have to be modified or removed

  • Preventive changes

    • technical debt has to be reduced

You see - lots of good reasons :-)

1.2. Why does software need improvement?

The most important reason is depicted in the following diagram: The cost-of-change of most software increases heavily over time…​ making those people really unhappy that have to pay for these changes (called maintenance, evolution, new-features or else)

An additional effect of long-term maintenance of software is the strong decrease in understandability: When a system matures it becomes more and more difficult to understand its inner workings, changes become increasingly risky and consequences of changes become difficult to foresee which can render effort estimations quite blurry.

target situation
Figure 1. Reality: Maintaining Software is too expensive

These negative effects share a few common root-causes:

  1. lack of conceptual integrity

  2. internal disorder

  3. overly complex internal structure, either of source code or data

  4. overly complex concepts (crosscutting solutions for fine-grained problems)

  5. overly complex or inappropriate internal processes

  6. inappropriate selection of technology (frameworks, libraries or languages)

  7. (you can surely find a few more…​)

1.2.1. Long-Term Goal

In the beginning, though, everything was fine: nice coupling and cohesion, appropriate technologies, well written code, understandable structures and concepts (see figure Goal: Maintainable Software)

But as more and more changes, modifications, tweaks and supposed optimizations were performed under growing time and budget pressure, things got nasty. The maintainers piled up so called technical debt (us software folks call it quick-hack, quick-and-dirty-fix, detours or abbreviations). We’re quite sure you know what we’re talking about - we experienced it over and over again, it seems to be the normal situation, not the (bad) exception.

Investment in methodical and systematic software architecture improvement will have the following effect.

target situation
Figure 2. Goal: Maintainable Software

1.3. How does aim42 work?

1.3.1. Three Simple Phases

aim42 works in a phased iterative manner:

aim42 phases
Figure 3. Three Phases of aim42
  1. Analyze: collect issues: problems, risks, deficiencies and technical debt within your system and your development process. Focus on problems in this phase, not on potential solution approaches. In addition, develop (and document) an understanding of internal structures, concepts and architectural approaches.

  2. Evaluate: determine the „value“ of issues and their solutions (improvements)

  3. Improve: systematically improve code and structures, reduce technical debt, remove waste and optimize.

These three phases are performed iteratively - as explained below. Several cross-cutting practices and patterns should be applied in all phases, for example documenting results, [collect-opportunities-for-improvement] or long- and short-term planning activities.

1.3.2. Common Terminology

aim42 relies on a common terminology, a small set of fundamental concepts.

aim42 concept map
Figure 4. aim42 domain terminology


Any problem, error, fault, risk, suboptimal situation or their causes within the [System] or processes related to it (e.g. management, operational, development, administrative or organizational activities).


Fundamental reason for one or several issues.


Solution, remedy or cure for one or several issues.

Cost (of issue)

The cost (in any unit appropriate for business, e.g. currency, effort or such) of the issue, related to a frequency or period of time. For example – cost of every occurrence of the issue, or recurring cost per week.

Cost (of improvement)

The cost (in monetary units) of the improvement, remedy, tactic or strategy.


Potential problem. Improvements can change associated risks for the better or the worse, even create new risks.

See also the more detailed Domain Model (not required for the casual reader)

1.3.3. Iterative Approach

In compliance with modern agile development methodologies, aim42 fundamentally depends on iteration and feedback between the phases.

Within each phase, you collect both issues and opportunities for improvement, as depicted in the illustration below:

collect issues improvements
Figure 5. Iterate and Collect

Issues and improvements need to be

  • related to each other: No improvement-idea without an existing issue - as we do not want to optimize "because we can".

  • evaluated in some business-compatible unit (Euro, $ or such) as described above. See Evaluate.

1.4. Patterns and Practices Provide No Guarantee

We are very sure that aim42 can work for your system or your organization. But (yes, there’s always a but) we cannot guarantee: Maybe your software is so extraordinaire, so very special, that it needs other treatment.

Maybe your organization does not fit our prerequisites, or is way more advanced than we anticipated in our approach…​

You have to use all practices, patterns and approaches of aim42 at your own risk and responsibility. We (the aim42 contributor team) can by no means be held responsible for any results of applying aim42.

2. Analyze

Figure 6. Analyze-Phase

2.1. Goals

  1. Obtain overview of intent, purpose and quality requirements of the system ([System]).

  2. Develop and document an understanding of internal structures, concepts and architectural approaches.

  3. Find all problems, issues, symptoms, risks or technical debt within the system ([System]), its operation, maintenance or otherwise related processes.

  4. Understand root causes of the problems found, potential interdependencies between issues

2.2. How it works

Systematically look for such issues at various places and with various people.

To effectively find issues, you need an appropriate amount of understanding of the system under design ([System]), its technical concepts, code-structure, inner workings, major external interfaces and its development process.

One serious risk in this phase is a premature restriction to certain artifacts or aspects of the system: If you search with a microscope, you’re likely to miss several aspects.

analyze-patterns overview

Figure: Overview of Most Important Analysis Pracices

Always begin with Stakeholder Analysis, then conduct Stakeholder Interview with important stakeholders.

Improve your Architectural-Understanding of the [System] by

Finally, do Root Cause Analysis of major issues found together with appropriate stakeholders.

Never start solving problems until you have a thorough understanding of current stakeholder requirements. Otherwise you risk wasting effort in areas which no influential stakeholder cares about.

2.3. Patterns and Practices for Analysis

Analyze Patterns

Figure: Detailed overview of Analysis Practices and Patterns

2.3.1. Atam

Architecture Tradeoff Analysis Method. Systematic approach to find architectural risks, tradeoffs and sensitivity points.


Apply the ATAM method to evaluate the software architecture regarding the compliance with quality goals.


The ATAM method consists of four phases as shown in diagram "Approach of ATAM".

Approach of ATAM
Figure 7. Approach of ATAM

The phases are:

  1. Preparation:

    1. Identify the relevant stakeholders: The specific goals of the relevant stakeholders define the primary goals of the architecture. Who belongs to these relevant stakeholders has to be determined by a Stakeholder Analysis.

  2. Kickoff:

    1. Present the ATAM method: Convince the relevant stakeholders of the significance of comprehensible and specific architecture and quality goals. ATAM helps identify risks, non-risks, tradeoffs and sensitivity points. Calculation of quantitative attributes is not subject of this method.

    2. Present the business objectives and architecture goals: Present the business context to the relevant stakeholders, especially the business motivation and reasons for the development of the system. Clarify specific requirements that the architecture should meet, for instance flexibility, modifiability and performance.

    3. Present the architecture of the system: The architect presents the architecture of the system. This includes:

      • All other systems with interactions to the [System],

      • building blocks of the top abstraction level,

      • runtime views of some important use cases,

      • change or modification scenarios.

  3. Evaluation:

    1. Explain in detail the architecture approaches: The following questions are answered by the architect or developers:

      • How are the relevant quality requirements achieved within the architecture or the implementation?

      • What are the structures and concepts solving the relevant problems or challenges?

      • What are the important design decisions of the architecture?

    2. Create a quality tree and scenarios: In the context of a creative brainstorming the stakeholders develop the relevant required quality goals. These are arranged in a quality tree. Afterward the quality requirements and architecture goals of the system are refined by scenarios which are added to the quality tree. The found scenarios are prioritized regarding to their business value.

    3. Analyze the architecture approaches with respect to the scenarios: Based on the priorities of the scenarios the evaluation team examines together with the architect or developers how the architecture approaches support the considered scenario. The findings of the analysis are:

      • Existing risks concerning the attainment of the architecture goals.

      • Non-risks which means that the quality requirements are achieved.

      • Tradeoff points which are decisions that affect the quality attributes positive and other negative.

      • Sensitivity points which are elements of the architecture that have formative influence to the quality attributes.

  4. Follow-up:

    1. Present the results: Creation of a report with:

      • Architectural approaches

      • Quality tree with prioritized scenarios

      • Risks

      • Non-risks

      • Tradeoffs

      • Sensitivity points


The ATAM method:

  • provides operational, specific quality requirements,

  • discloses important architectural decisions of the [System],

  • promotes the communication between relevant stakeholders.

The ATAM method does not develop concrete measures, strategies or tactics against the found risks.

ATAM has been successfully applied by many organizations to a variety of systems. It is widely regarded as the most important systematic approach to qualitative system/architecture analysis[1].


Evaluate an architecture:

  • as soon as possible,

  • already in the construction phase,

  • better not after the completion of the system.

2.3.2. Capture Quality Requirements


Make the specific quality requirements of a system explicit.


Invite authoritative stakeholders to a joint workshop (e.g. half- or full-day). Let them write quality scenarios to describe their specific quality requirements for the system. Moderate this workshop.

  • Use scenarios to formulate specific quality requirements.

  • Order those scenarios within a mostly hierachical quality tree, similar to [ISO-9126].

Scenario-based Quality Description

describes the reaction of a system to a certain event (or type of event).

quality scenario
Figure 8. Structure of Quality Scenarios

Although this definition is concise, it needs some explanation to become understandable. See figure Structure of Quality Scenarios:

  • An event can be a user clicking a button, an administrator starting or stopping the system, or a hacker trying to get unauthorized access. An event can also be a manager needing another feature, another manager wanting to reduce operation costs, or some government agency requiring financial data to be tamper-proof.

  • Needs moderation: Brainstorming quality requirements usually works well in moderated workshops. If given (even trivial) examples, every stakeholder will most likely write down several scenarios. We often received 80-120 different scenarios in one-day workshops.

  • Uncovers problems and risks: Scenarios collected within brainstorming sessions often contain hidden problem descriptions, risks or problems with the current systems.

  • Covers organization and process: Scenarios sometimes cover process or organizational aspects (like: release cycles should be faster than they are now). Move those to your Improvement Backlog.

  • Improves human communication: Different stakeholders often start communicating about the systeme or their requirements during such workshops. This kind of interaction should have happened long before…​


Use this practice when (authoritative) stakeholders are available for discussion or a workshop.

If you have well-documented, specific and current (!) quality requirements available, you might consider skipping this practice for now (although we’re quite sure it’s a good opportunity to learn a lot about the system, its stakeholders, their requirements and opinions).

  • The required constraints (aka quality attributes) of a system are made explicit.

Also Known As
  • Non-functional requirements (although this term is misleading, as functional requirements strongly influence the quality of any system!)

  • Documentation of quality requirements.


The workshop-based collection of quality requirements has been described by [Clements-ATAM].

  • Real-world examples of software quality requirements. Currently available only in German language on https://bitbucket.org/arc42/quality-requirements (this document is likely to be moved to github under the arc42 organization).

  • [Clements-ATAM], contains a brief description of scenario-based quality description and details how to setup such workshops.

2.3.3. Context-Analysis

  • Analyse external interfaces for risk, technology, business value and other factors.

  • Use the context to gain overview of the System within its business or technical environment.

  • Identify risks or problems in the immediate vicinity of the System.


We distinguish the following terms in context analysis:

Business Context

Adjacent organizations, applications, users or interfaces either requiring or providing services or data from or to the System. The business context can be used to describe the overall business process(es) the System is involved in.

Technical Context

Adjacent hardware or technical infrastructure, either required by the System or providing data or events to it. When the System can be used or operated in different hardware infrastructures, there might exist several different technical contexts.


Context analysis shall help identify issues associated with external interfaces, e.g. interfaces that:

  • influence critical quality requirements of the system (e.g. reliability, security, throuput, runtime performance, operation cost)

  • are overly complex

  • are brittle or fragile

  • are implemented with unsuitable technology

  • are underdocumented or poorly understood

  • transport critical data (important, sensitive, insecure)

  • transport especially huge amounts of data

  • have high operational effort

  • have high usage cost (e.g. cost-per-request or similar)

  • have high cost-of-change or high maintenance costs

  • are difficult or impossible to modify/enhance/change

  • suffer from operational failures or production issues

Note that user interfaces often belong to the context, especially with respect to the kind of data or events exchanged with users or user groups. Due to the importance of this topic, aim42 devotes an own section to it.


In the context diagram example of fig. Example of Context View you see some user roles and some external systems. The context diagram is accompanied by a tabular description of the elements and/or relationships. Example taken from the HtmlSanityCheck (HtmlSC) open source project.

Example of Context View
Figure 9. Example of Context View
Table 1. Business Context
Neighbor Description


documents software with toolchain that generates html. Wants to ensure that links within this html are valid.

build system

local html files

HtmlSC reads and parses local html files and performs sanity checks within those.

local image files

HtmlSC checks if linked images exist as (local) files.

external web resources

HtmlSC can be configured to optionally check for the existence of external web resources. Due to the nature of web systems, this check might need a significant amount of time and might yield invalid results due to network and latency issues.

In this example, the complete check has to be completed within 5 seconds (a quality requirement). As access to external websites or resources might be hindered by network latency or even failures, the external interface responsible for this requirement will likely contain risks.

2.3.4. Data-Analysis


Analyze and inspect the data created and manipulated by the system for its content, structure, quantity and size.


In data analysis you could examine the following topics:

Analyze Data Structures

Are data structures suited to represent the problem domain?

At first, make the structure of the existing data explicit, e.g. by creating a rough sketch of a data model as either informal diagrams, entity-relationship or class diagrams. Focus should be on overview: Where and how are what kinds of data stored in what format. What are the relationships between the data elements?

Second, create an explicit model the required domain data structures.

Some typical questions might help in finding problems:

  • structural differences between those two models?

  • differences in data types?

  • differences in plausibility or validity checking?

Analyze Data Access

Get an overview of data access paths: How is data read or written? Do the queries match their requirements, or are complex mappings or unsuitable indirections involved?

  • What queries or executed how often?

  • How large are the results in number or volume?

  • Do relationships between query results have to be computed, or do appropriate indices exist?

Analyze Data Size
  • Are some parts of the data especially large?

  • Is the relation between record-size (how large is a single record?) and record-volume (how many records exists?) plausible?

  • Do critical queries involve especially large parts of data?

Analyze Data Validation
  • How is data validated? (upon write, upon read, on client, on server, redundantly, uniformly)

  • Is validation consistent with current business rules?

  • Is validation overly complex?

  • Is validation implemented with appropriate technical means?

Analyze Data Actuality and Correctness

Especially in data concerning dynamic entities like people, organizations, markets, commodities etc., facts are very likely to change over time. Such data (stored facts) might become invalid sooner or later. Other types of information (like tax records, invoices or bookings on bank accounts) are created once and remain valid forever).

  • Peoples' address typically changes something between 2-10 times during their lives.

  • Empirical studies show that between 5 and 10% of business or job email addresses become invalid every year.

  • Which parts of the data are subject to (what kind of) changes?

  • Are parts of the data known to be invalid or contain invalid portions?

  • Does the System handle potentially wrong or invalid data appropriately?

  • Are there (organizational or technical) processes in place that deal with data inconsistencies or faults?

Analyze Data Access Protection
  • Is there an overview what kinds of data need which level of (access) protection?

  • Is there a security concept in place covering protection against unauthorized access?

    • How are users/roles/organizations allowed to access data managed?

    • Is there a process in place to revoke access for outdated users/roles/organizations?

  • Is there a plan what shall happen in case of security breaches or data theft?

  • How is data theft recognized?

Analyze Backup
  • Is there a universal backup strategy in place, covering all areas of data storage?

  • Does the backup strategy match the business criticality of the data?

  • To what extend has the backup been verified?

  • Does a fallback scenario exist in case of (partial or complete) data loss?

2.3.5. Debugging


Identify the source of an error (bug) or misbehavior by observing the flow of execution of a program in detail.

Many software developers we met violated the basic rules of debugging. They worked in haste, took wrong assumptions, imagined-instead-of-read or simply hunted bugs at the wrong parts of the system.

Debuggers are well-known and important tools for most software developers. Yet - finding bugs is often more difficult than expected - despite powerful tool support.

Approach the search for bugs, errors in the following order:

  1. Get a clear and precise description of the error, the detailed wording of all error messages, log messages, stacktraces or similar information.

  2. Know the context of the error: the exact version of the system, the operating system, involved middleware, hardware settings and so on. Have knowledge of the input data which leads to the error.

  3. Minimize external disturbance while searching for errors, you need to concentrate and observe details. Shut off chat and twitter clients, notifications and your phone. Send away your boss to an important management mission and lean back to reflect the error. Perhaps a colleague can support you.

  4. Reproduce the error in the live system. Don’t rely on the assumption you can reproduce it - make sure you can reliably really reproduce it.

  5. Obtain the exact version of all required source code and all involved data.

  6. Reproduce the error in development environment: This ensures your development environment is consistent to the live system.

  7. Call your error assumption into question. Realize what is symptom and what is cause of the error.

  8. Identify the building blocks which are involved in the error path.

  9. Understand the error scenario: You need to know the business or technical scenario (aka the process or activity flow) of the error: What steps within the system or at its external interfaces precede the error? This step is an example of View Based Understanding.

    1. Make this scenario explicit - draw or scribble a diagram. See the diagram "Divide and conquer" below as an example. Here the error arises in building block 1. You suppose the processing within the system is spaned by the blue marked data path in which the building blocks 2 to 6 are involved. Cut the path in half and check your assumption at the transition of one half to the other (here beetween building block 4 and 3). If no error is observable here then the error occures after the considered transiton. Otherwise you have to look for the error before the transition.

      Divide and conqer
      Figure 10. Divide and conquer debugging tactics
    2. Plan your debugging strategy: Think of the expected outcome of every part of your scenario.

    3. If you know you’re traveling to Pisa (Italy), you won’t confuse the Leaning Tower with an error.

  10. Look, don’t imagine: Sherlock Holmes, the succesful detective has formulated the golden rule of debugging: "It’s a capital mistake to theorize before one has data". Instrument the system or use step debugging. Look exactly what the messages are, read carefully.

  11. Change only one thing at a time and test if the error disappears: Aim for errors with a pistol, not with a scattergun.

  12. Apply the 4-Eye-Principle: Describe the problem and your state-of-debugging to somebody else. Especially clarify all your assumptions.


If locating errors takes very long, you’re propably facing one of the following issues:

  • You suffer from any assumption that’s currently not valid.

  • You think something instead of observing it - you let your mind deceive your eyes or ears.

  • You ignore the context: you test a wrong version, with wrong data or a wrong operating system.

  • Whenever a bug or misbehavior of a program is reported, debugging can help to identify its root cause.

  • Debugging can help in understanding a system by make its inner working explicit.

2.3.6. Development-Process-Analysis


Analyse and inspect the development process (as documented or described by stakeholders) for appropriateness, problems or problem-areas.


Under discussion!

2.3.7. Documentation-Analysis


Analyse existing documentation for availability, correctness, actuality, problems or problem-areas.


Under discussion!

Look for:

  • missing documentation,

  • over-documentation

  • outdated documentation

2.3.8. Infrastructure-Analysis


Analyze the technical infrastructure of the [System], e.g. with respect to time and resource consumption or creation. Part of Runtime-Analysis.


Infrastructure analysis is associated to the more general Runtime-Analysis, with focus on technical infrastructure for operation, test and development of the [System].

Inspect and analyse the technical infrastructure, for example the following aspects:

  • production hardware: does characteristics, type and size of the hardware suit the system and the business problem? Hardware might consist of several subsystems, like processing, various levels of storage (processor cache, RAM, flash, disk, tape or others), graphical and network interfaces and arbitrary specialized hardware

  • development and test hardware

  • software infrastructure, like operating system, required database, middleware, frameworks and libraries

It helps to measure runtime behavior agains expected or required values, for example processing time and memory consumption. Instrument System can support this type of analysis.

Specialized stakeholders (like datacenter administrators, operating-system or database experts, hardware designers) can often pinpoint critical aspects of existing infrastructures from their experience.

Apply View Based Understanding, especially an infrastructure overview (e.g. deployment diagram) to get an overview of existing hardware plus the associated software. Start with an hardware context and refine. Ensure you have at least all hardware-types (node-types) plus their relations (networks, buses) visible. Double-check this overview with the appropriate stakeholders.


The combination of hardware and software can be arbitrary complex. Even small configuration settings of operating systems (like block or packet sizes) can conflict with hardware capabilities, effectively ruining overall system performance.

2.3.9. Instrument System

Use retroactive modification of the executables which target cross-cutting concerns to make the existing software-base tell about it’s internals. Ways to achieve this can include Aspect Oriented Programming (AOP), Monkey Patching and other meta programming techniques.


Find out how the system is really used and what the runtime relationships are, as well as other facts that can not be easily determined by Static Code Analysis even in situation where the system under design is largely undocumented and the architecture work thus mostly relies on assumptions, interviews and lore.


In many languages today it is possible to define operation that alter the behavior of certain structures in the system without modifying the original source code. In Java this is often done by byte code instrumentation, in Ruby, PHP and some other languages there are built in mechanisms to (re-) define the behavior of system classes or libraries.

In theory instrumenting the system therefore is a straightforward process:

  • Identify and describe the concern that shall be explored (e.g. obectect-creation, function entries and exits, code execution or somethings else that can be described in the terms of the mechanism used).

  • Write the code that collects the data about the system behavior (e.g. sends it to a syslog, writes it to a file, sends it to a dedicated server, creates an SNMP Trap etc.)

  • Use the (language specific) mechanism to create the instrumented version of the system

  • Replace (part of) the currently operational system with the instrumented version

  • Collect the data

  • Replace the instrumented version with the previously operational version

In real life, since the mechanisms of instrumentation vary widely, specific ways must be found for each scenario.

While tools like AspectJ provide easy ways to instrument Java-Code and Ruby’s metaprogramming model allows for easy introduction of crosscutting functionality the same gets harder to do with other languages. In some languages it may be necessary to modify a dynamically linked library with central operations to introduce instrumentation without modifying the original system.

A special form of this pattern, especially useful for interpreted languages, is instrumenting the source code manually. Basically all you do here is manually type in the code to collect the information you’re interested in. In this case it is especially important to have a tried and tested way to replace the instrumented system back with the original system!

even if used cautiously, the instrumentation the system under design can entail heavy performance penalties (on execution time, space used, bandwith etc.) so alway make sure that there is a quick way to switch back to the original un-instrumented version.

The pattern is almost universally applicable as long as there is a way to introduce instrumentation to the executable and [operations] can be convinced that it is possible to to switch back from the instrumented version real fast.

2.3.10. Issue-Tracker-Analysis


Analyse entries from issue-tracker to identify critical areas, components or stakeholders.

Under discussion!

2.3.11. Organizational-Analysis


Analyse and inspect organization(s) responsible for the system.


Under discussion!

Look for:

  • violations of Conways' law

  • over or under-regulated processes

  • organization with overly strict constraints

  • organizations lacking constraints (anarchy)

  • orga-problems leading to IT problems

2.3.12. Qualitative Analysis


Find out (analyze):

  • wether quality requirements can be met by the system,

  • which specific quality requirements are risks with respect to the current architecture,

  • which specific quality requirements are currently non-risks

  1. Capture quality requirements to ensure you have explicit, specific, valid and current quality requirements available - preferably in form of scenarios.

  2. Prioritize these scenarios with respect to business value or importance for the authoritative stakeholders.

  3. For every important scenario:

    1. analyze the architectural approach the system takes,

    2. decide wether this approach seems appropriate or risky

  • Conducting workshops with a variety of stakeholders often leads to intense and productive communication.


Use qualitative analysis to support in the following situations:

  • You need to analyze which specific quality requirements are at risk and which will most likely be met by the system.

  • You have a variety of different stakeholders or groups which can all impose quality requiements - but have not yet agreed on a common set of such requirements.

  • A current and understandable collection of specific quality requirements for the system is missing.

Also Known As
  • Atam. Published by the Software Engineering Institute in numerous whitepapers and books, especially [Clements-ATAM].

2.3.13. Quantitative-Analysis


Measure artifacts or processes within the system, e.g. source code.


Under discussion!

2.3.14. Pre Interview Questionnaire


Prior to interviewing stakeholders, present them with a written questionnaire, so they can reflect in advance.


A specialisation of questionnaire - targeted to be used by stakeholders (aka your interview partners). As with the more general questionnaire you need to collect appropriate topics, questions and suggestions. Remember to apply stakeholder-specific communication: It might be useful to create different questionnaires per stakeholder or stakeholder-group. That’s more work for you as interviewer, but will lead to better interview results.

Mix open and closed questions:

  • open questions require stakeholders to formulate answers on their own. For example "How did you…​?" or "Please explain…​?"

  • closed questions ask stakeholders to select from several predefined choices.

Include a "Comments/Remarks" section at the end of the questionnaire, so stakeholders can comment on topics you did not consider in advance. The Pre Interview Questionnaire shall be handed over to the appropriate stakeholders in advance, a few days before the interview. As these documents will be read and processed by external and potentially critical stakeholders, you need to care for several details:

  • Stakeholder specific terminology: Ensure your questions will be understandable by the target audience. See [Stakeholder-Specific-Communication].

  • Ensure nice layout and (visual) readability. Your questionnaire shall be fun to work with.

  • Ensure timely delivery to your stakeholders, so they have enough time to think about their answers. Do never force your stakeholders to answer questions under time pressure.


Download a sample pre-interview questionnaire - currently only in German:

Also Known As
  • Interview checklist

2.3.15. Questionnaire


Support interviews with guidance and hints for appropriate questions.


Prior to taking interviews with stakeholders, formulate questions covering the topics or areas of information that:

  • might be important for you

  • your interview partners (== the stakeholders) have knowledge or experience in.

The questionnaire can be specific for a single interview or be a template for multiple interviews.


I (Gernot Starke) used such questionnaires within several technical reviews and audits. They helped my stay on track, cover a multitude of topics, even when I conducted several interviews consecutively.

I usually printed one copy of the questionnaire for every interview I had planned, so I could sketch notes - and always had the context of my notes already printed, saving a lot of note-taking effort.


Whenever you interview stakeholders, a thorough preparation will lead to better results, interviewers will be less likely to forget important topics.


Questionnaires can

  • serve as checklists for interviewers

  • aid in group-interviews to stay on track

Especially when multiple interviewers conduct interviews, preparing a questionnaire can lead to more homogeneous questioning.

Also Known As
  • Interview checklist

2.3.16. Requirements-Analysis


Analyze and document (current) requirements: required features and required constraints


Under discussion!

Look for and document:

  • required features and functions

  • required quality attributes (e.g. maintainability, security etc)

  • constraints that need to be met

  • organizational requirements or constraints

  • hardware requirements or constraints

2.3.17. Root Cause Analysis

To find mistakes is not enough. It is necessary to find the cause behind the mistake and build a system that minimizes future mistakes.
— W. Edwards Deming

Explicitly differentiate between symptom and cause:

  • Identify root causes of symptoms, problems or issues

  • Trace a problem to its origins


Some people fight problems, not their real cause: When faced with a problem our brains tend to start immediately to search for proper solutions for exactly this problem. For instance, if our application regularly crashes with Out-Of-Memory-Errors it might be a reflex to increase the memory settings. Instead we should ask if this is really the problem or only a symptom of the real problem, e.g. a programming failure in memory releasing. With an iterative process of asking "Why?" the causal chain must be traced down to the root cause.


Users of a system complained about low performance.

Developers started tuning the database, tweaking the application server, optimizing inner loops and so on (you pretty well know what I mean).

That did not solve the issue.

After applying Take What They Mean, Not What They Say we found out that users complained about low performance in data entry, as they had to switch back-and-forth between different regions on their input-screens.

The actual cause of their complaint was the improper field order in their input forms. After adapting this order by simply dragging fields/labels around the screen, users were perfectly happy with the systems.


This pattern should always be considered when faced with a problem.


You can eliminate the cause.

Also Known As

2.3.18. Runtime-Analysis


Analyze the runtime behavior of the [System], e.g. with respect to time and resource consumption or creation.

  • Ask stakeholders about perceived runtime behavior - double check by measuring.

  • Measure runtime behavior, e.g. with profilers, logs or traces.

  • Inspect artifacts created at runtime (e.g. logfiles, protocolls, system-traces) for information about problems, root-causes or system behavior.

  • Perform Infrastructure-Analysis to learn about the technical infrastructure.


Measuring might influence behavior. That can be especially disturbing in multi-threaded, multi-user or multi-core applications.

2.3.19. Software Archeology


Understand software by examining existing source code

  1. Make sure you have the complete code, scripts, frameworks and tools required to build the system.

  2. Ensure you have access rights to all required systems, at least to version control, database, participating servers etc.

  3. Ensure you can build the system from scratch (compile, load all dependencies, link or whatever steps are neccessary)

  4. Practice View-Based Understanding by sketching notes or diagrams. Get an aerial view, a glimpse of the topmost, biggest structures in the code.

  5. Try to understand the terminology of the original authors by scanning code and searching for multiple occurances. Start creating a glossary

  6. Introduce tracing or logging statements. Aspect-oriented tools (like AspectJ) might be helpful.


You have to understand a system with:

  • little or no current documentation.

  • no knowledgeable technical stakeholders or development team available


2.3.20. Stakeholder Analysis

Find out which people, roles, organizational units or organizations have interests in the [System].


Ensure that all concerned parties are adressed.


Get an initial list of stakeholders from project management.

Distinguish between roles and individuals. Some stakeholders need to be adressed individually, for roles it might be sufficient to identify any of several possible representatives.

Take the following list as examples of roles:

top-management, business-management, project-management, product-management, process-management, client, subject-matter-expert, business-experts, business-development, enterprise-architect, IT-strategy, lead-architect, developer, tester, qa-representative, configuration-manager, release-manager, maintenance-team, external service provider, hardware-designer, rollout-manager, infrastructure-planner, infrastructure-provider, IT-administrator, DB-administrator, system-administrator, security- or safety-representative, end-user, hotline, service-technician, scrum-master, product-owner, business-controller, marketing, related-projects, public or government agency, authorities, standard-bodies, external service- or interface providers, industry- or business associations, trade-groups, competitors

Include those stakeholders in a simple table:

Table 2. Stakeholder Table
Role/Name Description Intention Contribution Contact

name of person or role

responsibility for System

intention for/with/against System

what can/will/need they contribute to improvement of System, optionally or required

how to contact. For roles, name a primary contact person.


There are often more stakeholder roles involved than it is obvious. Especially those people not directly involved in project- or development work sometimes are forgotten, e.g. standard bodies, external organizations, competitors, press or media, legal department, employee organization.

2.3.21. Stakeholder Interview

Conduct personal interviews with key persons of the [System] or associated processes to identify, clarify or discuss potential issues and remedies.


Learn from the people who know or care about the [System] and everything around it.


Conduct a Stakeholder Analysis first to find out whom to interview.

Apply a breadth-first strategy, speak with people from different departments, roles, management-levels. Include at least business-people, IT- and business manager, end-user, developer, tester, customer-service, subject-matter-expert.

Plan the interview dates at least 5-10 days in advance, chose a quiet location, make sure nobody can overhear your interviews.

If possible, send out a stakeholder- or role-specific Pre Interview Questionnaire some days in advance.

Ensure a no-stress and no-fear situation. Never have top-managers or supervisors be present during interviews of their subordinates. Explain your positive intent and your role in the improvement project. Have water and cookies at hand. Make your interview partners feel comfortable and relaxed. Be honest and humble. Never ever promise something you cannot guarantee!

Ask open questions.

Tape or protocoll questions and answers.

Some typical questions, e.g.:

  • What is your role in this project?

  • What is great about the [System], the business and the processes?

  • What worries you about the [System]? What are currently the 3 worst problems?

  • What problems or risks do you see in (business/development/operation/usage…​)?

    • Can you show/demonstrate this problem?

    • How can I reproduce this problem myself?

    • When/where does it occur?

    • What are the consequences of this problem? Who cares about this problem?

    • How can we/you/somebody overcome this problem?

  • How are processes working? What are the differences between theory and practice?

  • If you had time, money and qualified people, what top-3 measures do you propose?

  • Is there anyone you think we need to speak with who isn’t on our list?

  • How would you like to be involved in the rest of this project, and what’s the best way to reach you?

In case people told you about severe problems, try to experience/see those problems yourself. At the end of the interview, give a short feedback and summarize important results to ensure you understood your interview partner correctly.


Expect the usual difficulties in human communication: people will love or dislike your work, the interview or the intent of your endeavour.

  • Some people will hold back information, either accidently or deliberately.

  • You have to create the big picture yourself. Most people tend to focus on their specific issues.

  • Double-check critical statements, as some people might exaggerate.


2.3.22. Static Code Analysis


Static Analysis can serve two purposes:

  • Analyse source code to identify building blocks and their dependencies, determine complexity, coupling, cohesion and other structural properties.

  • Detect certain types of bugs, dangerous coding patterns and bad coding style.


Use source code analysis tools to analyse static properties of the systems' source code, e.g. the following:

Coupling and dependencies

Where do the building-blocks (e.g. classes, packages, modules, subsystems) of your system depend upon? What are the intra-system call- and communication relationships?

  • Many projects (commercial and open-source) apply automated static code analysis as part of their build processes.


Apply static code analysis when the code base is medium sized or large and the appropriate tools are available.

  • Many metrics and tools are tailored to OO languages.

  • Dynamically typed languages often have limited tool support.

Also Known As
  • Code quality analysis

  • Software measurement and metrics

  • SonarQube, LGPL-licenced open-source platform to analyze code.

  • JDepend, open-source Java dependency checker.

  • Sonargraph, static code analyzer focused on software structure and architecture.

2.3.23. Take What They Mean, Not What They Say


Find out the real meaning/intention of stakeholders


Natural language has the risk that semantics on the senders' side differs from semantics of the receiver: People simply misunderstand each other because meaning of words differs between people.

Therefore: what people mean/want/need is sometimes not what they say. This is due either to * semantic differences on sender and receive sides, * stressful or inconvenient communication situations (e.g. "the boss is present", communication under pressure), * people are distracted or tired,

or other reasons.

NLP (neurolingustic programming) practitioners recommend to mirror things you hear to your communication partners in your own words. This might facilitate understanding.

When you have the slightest impression or indicator that your communication partner does not or can not communicate their real intention, you should clarify by giving explicit Fast Feedback.


Apply this pattern whenever you communicate verbally to other people (aka stakeholders), e.g. in meetings, conferences, phone calls etc.

Especially when verbal communication differs from paralanguage or gestures, you should clarify what your communication partner really meant.


Special thanx to Phillip Ghadir (who is too humble to claim this discovery) for giving this pattern its name.

2.3.24. User-Analysis


Get an overview of user-categories or -groups, their goals, requirements and expectations. Find out about issues users have with the system. Related to Stakeholder Analysis, Context-Analysis and Requirements-Analysis.

In contrast to the other analysis practices, user-analysis can also include useability, layout or design considerations.


2.3.25. View Based Understanding


Understand the inner workings and internal (code) structure of of the systems. Document (and communicate) this via architectural views, especially the building-block view.

  • Apply [arc42] views

  • Apply Static Code Analysis

  • Interview technical stakeholders

  • Start either from the

    • business context, mainly the external business interfaces

    • technical context, the involved hardware and network structure

    • known technology areas, i.e. products, programming languages or frameworks used

View based understanding
Figure 11. Three main views (building block, runtime and deployment view)

Use view-based-understanding when:

  • System has a medium to large codebase

  • Structural understanding of the code is limited: only few stakeholders can explain and reason about the code structure

  • Documentation of the code structure is not existing, outdated or wrong

  • Long-term maintenance and evolution of the system is required

  • Explicit overview of the system context with the external interfaces.

  • Overview of the larger units of source-code (subsystems, high-level components) and their relationships.

Also Known As
  • building block view (formerly known as logical view)

  • high-level overview

2.3.26. References

3. Evaluate

Figure 12. Evaluate-Phase

3.1. Goals

Make the issues, problems and risks found during the analysis comparable by estimating or measuring their value (that’s why we call this activity evaluate):

  1. estimate value of problems, issues, risks and their remedies

  2. prioritize issues, their remedies and improvement measures

Usually evaluation implies estimation, only in few cases can you measure or observe the evaluation subject and produce hard facts.

3.2. Estimation

evaluate domain conceptmap
Figure 13. Evaluation Concepts Domain Model
Table 3. Evaluation Domain Concepts
Domain concept Explanation Example


an approximation of any subject (here: issues,problems or remedies), which is needed because facts or real observations are not available or possible.


a recurring problem in the [System] or associated processes


an important element or foundation of the estimation.

  • number of developers on the system

  • Lines-of-Code (LOC)


a fixed setting for any parameter. See Explicit Assumption


measure, count, calculate gather real data for parameters

if every developer is concerned by the problem, we count their number.


see Estimate in Interval

between 15 and 25%

3.3. Pattern and Practices for Evaluation

3.3.1. Estimate Feature Value


Estimate the (monetary) value of a given feature, so you can compare features of the system with each other.

  • Involve business or management stakeholders, as they often have a clear notion of business value.

  • If you cannot determine real numbers available, use explicit assumptions

  • Instead of numbers, you might use categories or orders-of-magnitude (like small, medium, large). You should prefer numbers, though!

3.3.2. Estimate in Interval


Estimation is a guess, not a measurement. Estimates are uncertain, otherwise they would be observations (or measurements!).


Therefore, estimate in intervals, giving a lower and upper bound to your estimate. The difference between the two shows your confidence in the estimate. If this difference is relatively small, it shows high confidence.

Be aware of the anchoring effect http://en.wikipedia.org/wiki/Anchoring

Good estimates ensure that the estimated value will be contained in the interval with a very high probability.

Estimates often rely on assumptions - which should be Explicit Assumption.

3.3.3. Estimate Issue Cost


Find out how much a given issue costs in units of money or effort in a period of time or for every occurence.


Finding out the cost of an issue usually requires estimation or guessing, so there is uncertainty and propability involved.

For example, if a server needs to be rebooted once every 24hrs and an operator needs 30 minutes to perform this reboot (and corresponding activities) - then you can approximate the cost of this problem for, let’s say, a month:

5 workdays × 4 weeks × 30 min = 10hrs of operator-effort.

If you multiply with (approximate or average) wage, you get problem cost.

  1. If possible, try to measure or observe instead of guessing or estimating.

  2. If you cannot determine real numbers, use Explicit Assumption.

  3. If you need to guess, estimate or approximate

3.3.4. Estimate Improvement Cost

See: "Software Estimation. The Black Art Demystified (Steve McConnell)"

4. Improve

Figure 14. Improve-Phase

4.1. Goals

  1. Plan and coordinate measures and opportunities for improvements to eliminate problems and issues found during analysis. A whole category of practices is devoted to this step, called [Determine-Improvement-Approach]

  2. Apply selected opportunities for improvement

    • Change code, structures, concepts or processes to achieve better software,

    • Reduce costs and/or technical debt,

    • Eliminate issues found during analysis phase,

    • Optimize quality attributes (like performance, maintainability, security),

    • Optimize operation and administration processes, effort and cost.

4.2. Structure of the Improvement Phase

Concepts For Improvement

Some principles which you should consider whatever steps you take on your road to improvement.


Overall (strategic, long-term) decisions how to tackle improvement. Examples include Big-Bang, Strangulate-Bad-Parts, Change-Via-Split.


fine-grained practices or patterns, structured in several categories.

4.3. Fundamentals

For improvement we take a number of fundamental principles for granted, depicted in figure Improvement Fundamentals.

improve fundamentals
Figure 15. Improvement Fundamentals

These fundamental principles surely belong to software engineering good practices - but we consider them indispendsable for improvement projects.


Get feedback to your actions and changes as early as possible, so you can adjust as quickly as adequate.

Improve Iteratively

Improve in (potentially small) iterations and/or increments, so that change does not disturb or negatively affect the system, its associated processes and organisation. Iterations are the prerequiste for our whole phased improvement.


Verify the viability and effectiveness of improvements, usually in smaller scales with reasonable risks.


Always make sure that changes, even minor ones, leave your system intact. (The awesome Jerry Weinberg has written up several examples of such failures).

Reduce Complexity

Simpler solutions are most often easier to comprehend, maintain and operate. Therefore always strive for simplicity and the reduction of accidental, unneccessary complexity.

Explicit Assumption

Compensate missing facts (especially requirements, goals, estimates, opinions) by explicit (written) assumptions about those facts. See Explicit Assumption.

Group Improvement Actions

Group related actions, so that they refer to similar entities and potential synergies are utilized.

4.4. (Long-Term) Improve Approaches

The central decision you should take is the improvement-approach, the overall, long-range or strategic decision how you want to tackle your improvement.

improve approaches
Figure 16. Improvement Approaches

TODO: Describe Approaches


Create two or more identical copies of the whole system. Clean-up (reduce, gut) those copies individually, and then evolve the copies independently.


Split up the original system into (not neccessarily distinct) parts. Clean-up those parts individually, and then evolve the parts independently. (similar, but not identical to Change-On-Copy)


As value sometimes resides in data, keep data intact and replace the functional/service/process part of a system.


Start creating new backend parts. Frontend routes some requests to those new backend parts, others still to the existing ones. Gradually enhancing the new backend parts, frontend routes more and more requests to new backend.


Keep the existing system for a limited time, apply only critical bugfixes. In parallel, build a replacement system. Replace old by new at predefined time.


Incrementally (11 steps) build a replacement system. You can choose between Database-First, Database-Last and Composite-Database Approach.


Do a Big-Bang migration of the database, incrementally implement new applications and interfaces and connect the legacy system to the new database by forward gateways.


Keep the existing database for a limited time, incrementally implement new applications and interfaces and connect them to the legacy database by reverse gateways.


Combination of Database-Firt and Database-Last. Beside a forward- and reverse-gateway, there is a need for a transaction-coordinator.


Data-Migration Method without the need for gateways. Enables zero-downtime migrations by working with temporary data stores.




This approach has been extensively practiced by a Swiss Bank and published as a book. Underlying idea is to refactor those parts of the system(s) which are actually to be changed, especially to move all interfaces to new service standard and replace all legacy technologies and other couplings (via DB etc). Over time services should emerge that can be moved to a new platform altogether (from Mainframe to Java).

4.4.1. Big Bang Approach

Also Known As
  • test

  • test

4.4.2. Chicken-Little Strategy

to be completed…​

4.4.3. Database First Approach


The Database First approach, also called the Forward Migration Method, involves the initial migration of legacy data to a modern, probably relational, Database Management System (DBMS) and then incrementally migrating the legacy applications and interfaces. While legacy applications and interfaces are being redeveloped, the legacy system remains operable. This methodology falls within a group of methodologies which allow for the interoperability between both the legacy and target systems. This interoperability is provided by a module known as Gateway: a software module introduced between components to mediate between them. Gateways can play several roles in migration, insulating certain components from changes being made to others, translating requests and data between components or co-ordinating queries and updates between components.

The concrete gateway used by the Database First approach is called Forward Gateway. It enables the legacy applications to access the database environment in the target side of the migration process, as shown in Fig. 1. This gateway translates and redirects these calls forward to the new database service. Results returned by the new database service are similarly translated for used by legacy applications.

Figure 17. Database-First-Approach

The main advantage of this approach is that once the legacy data has been migrated, the latest programming languages and reporting tools can be used to access the data providing immediate productivity benefits. The legacy system can remain operational while legacy applications and interfaces are rebuilt and migrated to the target system one-by-one. When the migration is complete, the gateway will no longer be required and can be decommissioned as the old legacy system is shut down.

There are several disadvantages to this approach, in particular, it is only applicable to fully decomposable legacy systems where a clean interface to the legacy database service exists. Also, before migration can start, the new database structure must be defined. The major risk with this activity is that the structure of the legacy database may adversely influence the structure of the new database.

The Forward Gateway employed can be very difficult, and sometimes even impossible, to construct due to the differences between the source and the target in technology, in database structure, constraints etc..

Overall this is a rather simplistic approach to legacy system migration. The migration of the legacy data may take a significant amount of time during which the legacy system will be inaccessible. When dealing with mission critical information systems this may be unacceptable.

(taken from BISBAL, J. et.al.)

The database first approach (also known as forward migration method) provides for legacy databases to be moved unchanged into a relational database management system (RDBMS) to incrementally develop the user interface and the applications on the target system. But there is a need for a gateway to accept database calls from the legacy system and to redirect them to the new database system.

As BATEMAN and MURPHY say, there are a few problems and challenges:

  • to develop a forward gateway can be complex or even impossible, because there can be big differences in technologies according to structure, constraints, query languages and semantic heterogeneity.

  • usually reverse gateways are available on the market. Vendor tools often enable remote database access for example by sql. The purpose is that the legacy system becomes a big database server.

  • a pre condition to develop a forward gateway is, that the legacy system has clearly specified interfaces to the database layer. If this is not the case, there have to be expensive modifications to the applications, which can be time and cost intensive.

  • maybe there are a lot of external systems like reports, relying on the interaction with the legacy system. These systems have to be localized and analysed, so that they won’t crash after the migration.

  • the new database structure has to be designed and the data mapping has to be implemented before the migration can start. A problem can be data structures, that can not be adopted to the new data structure.

The main advantage of the database first approach is, that after the big-bang migration of the database, new programming languages and reporting tools can be used with the new database system. New applications can be developed in parallel to the legacy system, step by step, module by module, without an influence on the legacy system. As the migration is finished, the gateway can be deactivated and the legacy system can be shut down.

  • BATEMAN, A. und J.P.MURPHY: Migration of Legacy Systems. Working Paper: CA-2984, School of Computer Applications, Dublin City University, Ireland 1994

  • BISBAL, J. et.al.; A Survey of Research into Legacy System Migration. Technical Report TCD-CS-1997-01, Computer Science Department, Trinity College Dublin, 1997. http://citeseerx.ist.psu.edu/viewdoc/summary?doi=

4.4.4. Database Last Approach


The Database Last approach, also called the Reverse Migration Method, is based on a similar concept to the Database First approach and is also suitable only for fully decomposable legacy systems. Legacy applications are gradually migrated to the target platform while the legacy database remains on the original platform. The legacy database migration is the final step of the migration process. As with the Database First approach, a gateway is used to allow for the interoperability of both information systems. In this case a Reverse Gateway enables target applications to access the legacy data management environment. It is employed to convert calls from the newly created applications and redirect them to the legacy database service, as shown in Fig. 1.

Figure 18. Database-Last-Approach

If the legacy database service is to be migrated to a relational database management service, then the target applications will be developed completely with SQL calls to the data service. It is these calls that are captured by the Reverse Gateway and converted to the equivalent legacy calls. The Database Last approach has a lot in common with the client/server paradigm. The legacy database takes on the role of a database server with the target applications operating as clients. There are commercial products available which effectively act as reverse gateways.

The Database Last approach is not without its problems however. Performance issues can be raised with regard to the gateway. The Reverse Gateway will be responsible for mapping the target database schema to the legacy database. This mapping can be complex and slow which will affect the new applications. Also many of the complex features found in relational databases (integrity, consistency constraints, triggers etc.), may not be found in the archaic legacy database, and hence cannot be exploited by the new application.

This approach is probably more commercially acceptable than the Database First approach as legacy applications can continue to operate normally while being redeveloped.

However, the migration of the legacy data will still require that the legacy system be inaccessible for a significant amount of time. When dealing with mission critical information systems, this may be unacceptable

(taken from BISBAL, J. et.al.)


4.4.5. Composite Database Approach


In Composite Database approach, the legacy information system and its target information system are operated in parallel throughout the migration project. The target applications are gradually rebuilt on the target platform using modern tools and technology. Initially the target system will be quite small but will grow as the migration progresses. Eventually the target system should perform all the functionality of the legacy system and the old legacy system can be retired.

Figure 19. Composite-Database Approach

During the migration, the old legacy system and its target system form a composite information system, as shown in Fig. 1, employing a combination of forward and reverse gateways. The approach may involve data being duplicated across both the legacy database and the target database. To maintain data integrity, a Transaction Co-ordinator is employed which intercepts all update requests, from legacy or target applications, and processes them to identify whether they refer to data replicated in both databases. If they do, the update is propagated to both databases using a two-phase commit protocol as for distributed database systems.

Analysing non-decomposable legacy components can be very difficult. In the worst case the component must be treated as a black box. The best that can be achieved is to discover its functionality and try to elicit as much legacy data as possible. Sometimes using existing legacy applications, (e.g., database query, report generation, and access routines), is the only way to extract the legacy data. Once the functionality has been ascertained, the component can be re-developed from scratch. It can often be very difficult to identify when legacy data or functions are independent; in many cases they may simply have to be replicated and target copies co-ordinated until the entire legacy system can be safely retired.

The Composite Database approach eliminates the need for a single large migration of legacy data as required in the Database First and Database Last approaches. This is significant in a mission critical environment. However, this approach suffers from the overhead not only of the other two approaches but also the added complexity introduced by the co-ordinator.

(taken from BISBAL, J. et.al.)


The Composite Database approach is applicable to fully decomposable, semi-decomposable and non-decomposable legacy systems. In reality, few legacy systems fit easily into a single category. Most legacy systems have some decomposable components, some which are semi-decomposable and others which are non-decomposable, i.e. what is known as a Hybrid Information System architecture.


4.4.6. Butterfly-Methodology


Data-Migration Method without the need for gateways. Enables zero-downtime migrations by working with temporary data stores.


The Butterfly-Methodology focuses on data. There is no need for a gateway like in the Chicken-Little Strategy. At the beginning there is a initial data migration, which can be used to develop the new application without an influence on the legacy system. When the migration process starts, the data of the legacy system gets freezed and set to read-only. From now on data changes will be stored in a temp-store. A Data-Access-Allocator (DAA) decides, if a request has to be send to the temp-store (for already changed data) or to the original database. With the help of a Chrysalizer (Data-Transformator), where transformation rules are implemented, all the data from the read-only database will be moved to the new system. No data will be lost, because changes are written to the first temp-store. When the inital migration is finished, the data of the temp-store will be migrated; changes will be written to a second temp-store and the first one is set to read-only. This process will continue until the time period of the migration is so short, that there was no change in between. At this moment, the legacy system can be shut down, the last temp-store gets migrated and the new system is turned on. This approach helps to migrate a productive system without downtime. Another pro is, that the process can be canceled at any time by rolling back the temp-stores. It is also possible to do tests of the parallel development with actual data. A problem can be the amount of hardware that is needed to keep all the temp-stores if you have a mass of data. Also it can be very expensive to implement the DAA.

Figure 20. Butterfly-Methodology

If the Butterfly Method will be successful depends on the factor v / u, where u is the speed of the Chrysalizer and v the speed of the DAA to setup new temp-stores. If v = 0 this approach is similar to the [Big-Bang Strategy], if v > u the migration will never end.


Apply this pattern if you need to migrate a mass of data without downtime.


Enables zero-downtime migrations by working with temporary data stores. If the amount of data is huge, there is a need for a lot of hardware.

Critical success factors are:

  • a very good unterstanding of the old and new system

  • a initial migration without errors / mistakes

  • a fast Chrysalizer

  • a efficient Data-Access-Allocator

Also Known As

4.5. Categories of Improvement Practices

We divide improvement practices into several categories (shown in the figure below). In contrast to the (more strategic) approaches these practices are more a tactical nature.

improve practice categories
Figure 21. Categories of Improvement Practices

4.6. Practices to Improve Processes

Practices for Improve Processes
Figure 22. Practices to improve processes

4.7. Improve Architecture and Code Structure

This category contains a fairly large number of practices.
Practices to Improve Architecture
Figure 23. Practices to improve architecture and code structure

4.7.2. Anticorruption Layer


An anticorruption layer is a logical layer that provides a stable interface to (potentially) volatile software components. As long as this interface remains untouched developers can implement changes or even exchange own or third-party software without affecting the clients of this interface.


Here are some real-life experiences:

  • Anticorruption layer for a search-index to defer the decision if the best performance can be achieved with Elastic Search, Solr or a self-developed Lucene index.


Apply this pattern when clients shall be protected from internal changes in a module or subsystem.

  • Allows to (ex)change software elements without affecting depending components

  • Introduces one more level of indirection and thus may increase complexity

Also Known As

4.7.3. Improve Logging


Employ sophisticated logging mechanisms such as modern logging frameworks, distributed log collection and visualization tools in order to gain more detailed information about the system during runtime with a minimal or predictable performance impact.


While some time ago it was quite common to output log statements to standard out, people usually use logging frameworks nowadays that give more control about what should be logged and where the log entries should go.

However, it turns out that such logging frameworks have some feature gems that are not widely known or used. To name a few:

  • Diagnostics Contexts (also known as Mapped Diagnostics Context (MDC) or Nested Diagnostics Context (NDC)) help to store additional context information for all succeeding log statements. Usage examples for such contexts are the login name of the current user, correlation IDs in order to enable cross-application log tracing or transaction IDs to have the possibility to filter all log entries that belong together.

  • Additional log levels or markers help to make it easier to filter the log stream. It is a good advice to think about the marker and log design at the beginning of the project and try to agree on a common way to phrase log statements.

  • Asynchronous appenders (i.e. log emitter) allow high-throughput logging, which lower impact on the application’s performance.

  • Structured log formats produce a machine-readable output. Usually, log files are written using a more or less standardized text output. Log files in XML or JSON can be parsed and digested easily and allow for better filtering since more information, like diagnostics contexts, is always available in these formats.

  • Filters enable context-based logging and can dispatch log entries to different log appenders. For instance it is possible to log warnings only but switch to debug logging for a specific user.

In some environments it turns out to be problematic to rely on a single logging API. This could be the case if the application runs within a container or container-like framework that already employs a configured logging framework. In order to be independent of conrete logging frameworks, logging facades like SLF4J should be preferred over using the framework’s API directly.

Despite the focus on the software development, logging is also an operations topic. Often it turns out to be difficult to get recent log files from the operations team. Another pain point is that useful log information is scattered across multiple log files, stored at different locations on different systems. Log aggregation tools such as Splunk, Logstash, Apache Flume or fluentd can consume and unify log data from different sources (e.g. files, syslog, network), can trigger alerts or index the log stream in order to make them searchable. Now, with tools like Kibana, log data of a system of systems can be easily analyzed and visualized. Correlation IDs contained in the logs can be used to trace certain business-related requests across multiple distributed systems easily.

Using such features makes the problem analysis easier and more data is available in a standardized fashion.


Most projects write log files in a more or less sophisticated fashion, in many cases log messages are phrased in a rather unstructured way. It turns out that a well-designed logging concept helps to make the log stream easier to understand. This concept should provide some guidelines regarding which log level should be used in which situation, how the wording of log messages could be unified and which additional log levels or markers shall be used for what purpose.

In a customer project we used an object-relational-mapping (ORM) tool for a database independent access layer. The data access was inherently transactional and created a lot of database traffic so that deadlock situations on the database were expected and properly handled with a delayed retry mechanism.

While this approach worked quite well, we got frequently complaints from the operations team, which reported a number of ERROR log messages along with longish stacktraces that set their alarm bells off. These log messages were written by the ORM tool whenever a DB deadlock was experienced. Since the application could perfectly deal with this situation this was not an error anymore and should have been logged as WARN or INFO at best. The problem was that a third-party framework used the wrong log level and was thus causing a lot of confusion. Bear this in mind when working on a framework-like codebase and thinking about log levels.

  • An excessive amount of log statements is likely to have negative impact on the application’s performance. The impact is however manageable by using

    • guarded log statements that will only be constructed if a certain log level is enabled,

    • asynchronous appenders (like the disruptor-based approach used by Log4J 2),

    • context-sensitive logging (e.g. to enable debug logs only for a certain scenario or user).

  • Collecting and indexing a huge amount of log data requires additional storage, approx. by factor 10. Think of retention policies in order to make the data stream manageable.


This pattern should always be considered.

  • Improved understanding of the runtime behavior of an application or a system of systems.

  • Log messages are well-structured and more meaningful as they carry more context information (in case MDCs are used).

Also Known As
  • This pattern is an important enabler for a successful [Runtime-Artifact-Analysis].

  • Instrument System is very similar to this pattern, however it is limited to a temporary instrumentation that is needed during the Analysis phase to identify or scope a certain problem that cannot be isolated without modifying the code.


4.7.4. Interface Segregation Principle


Reduce coupling between clients and service providers.


Service components may provide more functionality than required by one client. To remove the client’s dependency from functionality not required introduce interfaces that are tailored to the client’s needs.


Apply when

  • clients only require a restricted functionality from a complex service,

  • you have to deal with low cohesion components you cannot change

  • Reduces coupling between client and service providers. Changing the service provider interface will affect fewer clients.

  • Introduces additional interfaces that must be maintained.

  • You have to find a good compromise between "good client fit" and the number of interfaces.

Also Known As

4.7.5. Introduce Boy Scout Rule

The “Boy Scout Rule” for software development basically states that we

“Always check a module in cleaner than when you checked it out.”.
— Robert C. Martin

Uncle Bob (Robert C. Martin) proposed this adoption of the rule from the boy scout rulebook which reads “Try and leave this world a little better than you found it.” for the software development world in an article in Kevlin Henney’s “97 Things a Programmer Should Know” [Henney].


Enable crosscutting architectural improvement even if it is not feasible to change the whole codebase.

Often the introduction of concepts like layering is deemed “impossible” due to the huge codebase that would be affected. In these cases the Boy Scout Rule approach is a lightweight way to enhance the code quality one day at a time.
  • Drafting from an [improvement-backlog], define a specific rule set on how to improve the contents of specific file types.

  • Specify how much effort should be allowed to perform each specific clean-up operation

  • Specify how to proceed if the cleanup takes up too much time

  • Revisit the rule set regularly

  • Install a mechanism to ensure that the things that where too big to be cleaned up while visiting the file will end up in the [improvement-backlog].

Example Boy Scout Rule agreement

This is a very concrete agreement from a specific project - yours should look rather different.

Boy Scout Rule agreement for project X from 2014-02-19 onwards: . Apply defined source code formatting (via IDE) to adhere to coding style
If the formatting introduces errors and those errors can not be fixed within 10 Minutes revert changes and add the file to the "redo formatting list" (e.g. add an TODO REFORMAT comment, if such a comment already exist add an exclamation mark each time you handle the file)

  1. Move SQL strings to the db-encapsulation layer and replace the former direct database calls by appropriate calls to the correct architecture elements
    If this takes longer than 20 minutes revert changes and add file to the list "difficulties with database extraction" (e.g. add an TODO DB-EXTRACT comment, if such a comment already exist add an exclamation mark each time you handle the file)

  2. Remove magic numbers from source code and replace them with constants (e.g. replace if (item.id > 99) with if (item.id > Item.COMPOUND_ITEMS_THRESHHOLD).

  3. If time allows replace the former "magic number conditionals" with a function on a business logic level (e.g. replace if (item.id > Item.COMPOUND_ITEMS_THRESHHOLD) with if (item.is_compound())


Introducing the Boy Scout Rule on a heavily deteriorated code base induces heavy payback on [technical-debt] and often gets challenged by team members and senior management. It is important to point out that the extended time spent on fixing the artifacts “as the teams goes” actually is the explicit payment of the [technical-debt] interest rate.


Sometimes the Boy Scout Rule can be taken as a means by itself. In these cases the higher goals tend to be forgotten and thus


The pattern “Introduce Boy Scout Rule” can always be applied.
Some of the most effective uses are

  • unstructured code (no layers, no separation of concerns etc.)

  • systematic weaknesses (insecure logging, insecure handling of database inserts etc.


The introduction the Boy Scout Rule often proved to enable structural improvements as a prerequisite for higher level architectural improvements. Also it heightens the team’s awareness of good practices in their code base.

The introduction of the Boy Scout Rule leads to a dramatic shift in the distribution of the code quality because those parts of the system that get changed the most also get the most care. For more stable parts of the system other approaches have to be utilized.

Also Known As

The original description of the boy scout rule can be found online at [Boy-Scout-Rule-article].

4.7.6. Manage Complex Client Dependencies With Facade


Simplify the interaction of a client with a set of service components.


When clients use a set of components with repeating patterns these interaction patterns are implemented in a Facade component.

The interface the Facade provides to the client is tailored to the client’s need. Technical details that are specific for the service component implementations are handled inside the facade.


Consider a Facade if you must use generic frameworks or systems you cannot modify e.g. legacy systems.


Apply this pattern when clients use a set of components in stereotypcial fashion. Things that can be handled by a facade:

  • recurring control flows

  • technical details

    • configuration of components

    • resource lookup

    • error handling

  • Enhances Information Hiding. Clients do not need information about the components' technical detail.

  • Supports DRY principle: complex interactions are implemented in one place. No need to reimplement this in different clients.

Also Known As

4.7.7. Measure


If you don’t measure it, you can’t optimize it. — Coda Hale


TODO: explain different kind of metrics (static-code, runtime, organisational…​)


If you measure too many different parameters or attributes, you might drown in numbers.


This pattern should always be considered.

Also Known As
  • quantitative analysis

  • quantitative runtime analysis

  • profiling

  • organisational metrics

4.7.8. Use Invariants To Kill Zombies


Provide a safe approach in situations where it seems to dangerous to delete code or whole modules from a huge system because Static Code Analysis can’t recognize whether the code is still in use or not.


Oftentimes old systems contain lots of code that probably is no longer in use but still has to be tended to. Such code puts a burden on every cross-cutting change - from the year-2000 efforts of the late nineties to the upcoming end-of-unix-system date rewrites. New processor architectures, new versions of operating systems with a different handling of the byte-order and all kinds of external regulations are just some examples for things that make it necessary to make changes to all existing code — whether it is still in use or not. This code is deemed dead, but like the proverbial zombie it still goes around and munches on everybody’s brain when it is time for the next system-wide change.

This kind of zombie can be killed more safely by employing invariants.

An [invariant] — as described by Bertrand Meyer in [Object-Oriented-Software-Construction] — is a logical expression that always is true for a given set of circumstances. He proposes to actually verify those invariants in the code itself. What happens if the invariant does not hold true is open to discussion - in some circumstances it’s best to fail-fast but when improving legacy software with hundreds or thousand of users this often is not an option.

So if we want to make sure we can delete this code our invariant is simple:

assertTrue(false, "We should not be here" + __FILE__ + __LINE__ );

How to implement assertTrue() for this case is hard, though.

As just pointed out, the simple “let the program die” approach might not be appropriate.
Just logging the fact might not have a sufficient effect.
Sending an e-mail requires at least some infrastructure (and infrastructure code)
Sending an SNMP-Trap might not be feasible in the environment.

And so on.

This is a classical situation that calls for trade-off decisions, but since this piece of code should never be called anyway things like sending an e-mail or calling some webservices are not so far out of the question.

If a huge number of deployments is possible without problems it can also be feasible to de-escalate slowly and use more and more intrusive ways to handle the failed invariant — write a log entry in the first two weeks, send an SNMP trap in the next four weeks and after that send an e-mail (although it doesn’t hurt to keep the logging turned on).


In several cases this approach helped to delete up to 50% of the code base.

  • Sometimes the Zombie is buried to early — to be on the safe side the presumably dead code should live through at least each season. For huge systems that really means 366 days.

  • The presumably dead code might be called much more often than anticipated - in these cases a highly invasive reaction, like sending an e-mail, can lead to side-effects that are close to a denial-of-service attack.


This pattern can be applied whenever the code-base has gotten too big and there are parts of the system that are perhaps unused (e.g. dead) but still add to the weight of the system.

  • Dead code can be safely deleted

Also Known As
  • Use Static Code Analysis to find candidates, entry points and exit points.

  • Using invariants to kill zombies is a special case of [Assertions] in the context of architecture improvement.

  • Introducing invariants to verify that the code is really dead is a specific way to make Explicit Assumptions


4.7.9. Improve Feedback From And For Stakeholders


Effectively collect feedback from various stakeholders.


It is expensive to collect information (problems, opinions etc.) from stakeholders (customers, support staff, developers, backoffice etc.) via surveys, interviews or meetings (e.g. ). There are possibilities to offer low-threshold services for involved people to give feedback. Possibilities e.g. are:

  1. Tracking systems in the user interface

  2. Easy-to-use contact possibilities in the system’s user interface

  3. Ticketing/issue management software

  4. Wikis

  5. System-supported surveys

This information might help in finding issues, calculate their costs and prioritize it. Additionally to quantitative analysis, qualitative analysis might give improvement hints.


Since most improvements are based on voluntariness (all examples except a), the information might be biased.


Many of the tools supporting this use case are used for a group of stakeholders and can possibly be used for others as well (e.g. ticketing systems or Wikis for developers in open source projects).


Stakeholders give valuable information, their satisfaction with the system increases.

Also Known As

4.8. Practices to Improve Technical Infrastructure

Practices to Improve Technical Infrastructure
Figure 24. Practices to improve technical infrastructure

4.9. Practices to Improve Analyzability and Evaluatability

Practices for Improve Analyzability
Figure 25. Practices to improve analyzability

5. Cross-Cutting Practices and Patterns

5.1. How it works

  1. Start with collecting issues - mainly in Analyze phase. Based upon your findings here, maintain an Issue List

  2. Evaluate those, determine values, preferably cost. This ensures you later solve important and relevant issues.

  3. Collect Opportunities for Improvement and evaluate those too.

  4. Align issues and potential improvements, Plan Improvements

  5. Continously strive to increase your Architectural-Understanding, as this facilitates identification of additional issues and improvements.

issues and improvements
Figure 26. Collect issues and improvements

5.3. Architectural-Understanding

Develop and document an understanding of internal structures, concepts, architectural approaches and important decisions of the [System].

5.3.1. Description

Collect and organize architectural information about the [System]: Document structures, concepts, decisions, interfaces etc. of the [System] to locate issues, risks and opportunities for improvement.

  • Business or technical system context, with external interfaces. Learn this from Context-Analysis or Infrastructure-Analysis.

  • Solution strategy, often to be learnt from [Stakeholder-Interviews] with experienced developers of the system.

  • Building block structure, the static organization of the source code. At least elaborate the highest level of code blocks (level 1 building blocks)

  • Runtime structures, like important use-case scenarios. Sometimes this can be learned from Runtime-Analysis.

  • Infrastructure and deployment, often derived from Infrastructure-Analysis.

  • Crosscutting and technical concepts, like domain models, persistence, user-interface and other concepts.

  • Important architecture and design decisions taken and revoked during development of the system.

5.3.2. Experiences

Architectural understanding can be gained in small increments, so there is no need to reserve long times just for documentation.

Understanding should come from various sources - see all the Analyze practices.

  • [arc42] provides a free and pragmatic template for software architecture documentation. It’s available in various formats (e.g. Microsoft-Word (tm) and AsciiDoc).

  • View Based Understanding

5.4. Collect Opportunities for Improvement

You should look for improvement opportunities, remedies, measures, tactics and strategies in all of the aim42-phases.

collect remedies
Figure 27. Collect Remedies in All Phases

5.5. Collect Issues

You should constantly watch out for issues (problems and risks), especially during analysis activities like [Stakeholder-Interviews] and others.

The artifact (physical collection) is the Issue List.

Regularly match these issues to your collection of possible improvements.

5.6. Expect Denial

Some people will oppose your findings, will whitewash or sugarcoat issues, problems or root causes. Regardless on how careful you prepared your analysis, they will try to diminish, attack or dispute your findings.

5.6.1. Intent

  • Prepare you (as analyzer or evaluator or systems) for serious opposition and resistance by some stakeholders.

  • Describe which kind of reaction might be turned into acceptance.

  • Describe what might be gained by certain slightly negative reactions.

5.6.2. Description

Reaction levels
Figure 28. Levels of Reaction when presented with problems

From enthusiasm to neutrality things will be easy, but from here on it gets interesting or difficult, however you might call it.

  1. Enthusiasm: Some people will embrace your findings - like "that’s what we always said…​". Enthusiasts sometimes expect that findings or the appropriate improvement approaches directly improve their own situation.

  2. Agreement: Others will agree, without further ado.

  3. Neutrality: Some stakeholders won’t care. These are probably unconcerned by any finding.

  4. Amazement: Your results will amaze or astonish some people. Although they would never have expected your findings, amazed stakeholders might be convinced to agreement or neutrality by using explanation and proofs in stakeholder-specific language or communication. On the other hand, amazed stakeholders pose the serious risk of becoming more negative (doubtful or resisting) if you fail to convince them - or if other people (your opponents, for example) manage to bring them over to the dark side…​

    Always ask amazed stakeholders why for the reasons of their amazement - that can help you in your argumentation.

  5. Doubt: You will hear or read "Can’t be, impossible!"or similar expressions from some people. If these stakeholders can explain the reasons for their doubts, you might find ways to improve your explanation (maybe your issues were simply ill-formulated) or you have to look for additional and better ways to explain. Doubt can lead you to errors or ommissions in your own argumentation or conclusions.

    Some doubtful stakeholders will be emotional - and therefore not open for rational or objective arguments. That’s a serious and difficult communication problem - beyond the scope of this guide.

  6. Minimization, sometimes disavowal: This is the first level of denial. The fact itself is accepted, but its consequences, evaluations or seriousness are denied. In practice we encountered this phenomenon quite often: Affected stakeholders repeat their assessment "problem acknowledged, but the consequences are only minimal" like a mantra. Other stakeholders, especially doubtful or amazed ones, might start to believe in this minimization tactic - especially if the truth implies inconvenient or uncomfortable changes in their own working environment.

  7. Resistance: Findings are opposed, either actively or passively.

    In case you encounter minimization or resistance, get support from the highest management level you can access: As a consequence some, if not many, minimizing or resisting stakeholders will turn to your side.

  8. Hostility, or "Shoot the messenger". Always remain calm and polite - but hard in your argumentation and facts. Hostile stakeholders can rarely be convinced of something, but need to be handled with diplomacy, politics and organizational skills (none of which we can cover here).

    Be prepared for hostile actions, though: In case of critical issues, always keep details documentation of their origin. Be prepared to proof those issues, remove even minor omissions or formal weaknesses in your argumentation. Your issues and Root Cause Analysis has to be flawless and backed by meticulous research and management support. Ensure Traceability of your chain of reasoning! Keep written records of [Stakeholder-Interviews] and of suspicious pieces of source code, or documentation.

Let others review your findings before publication.

5.6.3. Experiences

In one audit of a European Logistic Company (>40.000 employees) we found serious issues within their development processes, in addition to some issues in their source code. The process problems caused massive (> 3month) delays in delivery of working software to production, whereas the pure software bugs were relatively minor in their consequences. When we presented these issues, all process-related issues were minimized or doubted by senior management of the IT-department.

With the help of the CIO, we identified those minimizers to be the root-cause of most process-issues, as they had themselves introduced inefficient, formal and bloated processes.

5.6.4. Consequences

Especially when presenting results to (opposing) management stakeholders, you should be able to verify all your claims. In critical cases you should keep written protocols and note who-said-what in your stakeholder interviews.

5.7. Explicit Assumption

Compensate missing facts (especially requirements, goals, estimates, opinions) by explicit (written) assumptions about those facts.

5.7.1. Description

Making assumptions explicit is fundamentally important to Capture Quality Requirements, so that development teams don’t need to rely on implicit assumptions or requirements.

When evaluating problems, risks or remedies, we often need to estimate or assume stuff like duration, cost, workload or others. These estimates or assumptions need to be made explicit, so that others can reproduce or understand our evaluation. In case of numerical estimation, it helps to apply Estimate in Interval

Also known as educated guess.

5.8. Fail Fast

The later a lack of quality is identified the higher are the costs to fix it. Continuously evaluate the quality of work artifacts and immediately take countermeasures or pull the plug as early as possible. Similar to Fast Feedback.

Suitable methods to identify such situations are:

  • Code reviews

  • Architecture reviews

  • Peer reviews

  • Testing in early stages

5.9. Fast Feedback


See also Fail Fast.

5.10. Impact Analysis

5.10.1. Intent

Determine what impact (in code, concepts, data and the organization) a specific action or issue (e.g. refactoring, recurring problem) will or might have. Identify the resultant effects on system development and operations.

  • Failure-Mode-and-Effect-Analysis (FMEA), a method for failure analysis, widely used in various industries

5.11. Improvement Backlog

Keep a public, written backlog of possible improvements, remedies, tactics or strategies.

  • Revise this backlog in regular intervalls.

  • Define the owner role for this backlog, similar to the product owner in Scrum.

  • Enhance the backlog with information from the [evaluation] phase, like cost, effort or risk.

improvement backlog
Figure 29. Improvement Backlog

5.11.1. Intent

Collect all known issues and problems within a system or its associated processes. Make the issues comparable by evaluating each one, usually using economical units like money or time. Align carefully with Issue List.

5.11.2. Content

Table 4. Improvement Backlog
ID Improvement Description min Cost max Cost Related Issues



short description of this improvement or remedy

minimal estimated cost or effort

maximal cost or effort

links to related issues

5.11.3. Representation and Tools

Try to use a similar documentation approach like for Issue List. It should be as easy as possible to link issues to improvements and vice versa.

5.12. Issue List

A collection of issues (problems, risks) found during Collect Issues.

5.12.1. Intent

Collect all known issues and problems within a system or its associated processes. Make the issues comparable by evaluating each one, usually using economical units like money or time.

5.12.2. Content

Table 5. Issue List
ID Issue Description Frequency min Value max Value Improvements



a short description of the issue

how often does the issue occur, once, daily, weekly, with every new feature?

minimal value

maximal value

links to improvements

5.12.3. Representation and Tools

It’s difficult to decide how much formalism to apply in collecting issues and problems: Sometimes a wiki-page might suffice, for other systems a full-blown issue-tracker can be useful.

As always: documentation is only valuable if it can be found easily, which makes electronic approaches more viable.

For every entry in this issue list we need to Estimate Issue Cost, an estimation of the cost of this issued in any business-related unit.

In case you already have identified or developed [opportunities-for-improvement] adressing this issue, links to the corresponding improvements (remedies, tactics, strategies, changes) in the Improvement Backlog are neccesssary.

5.13. Plan Improvements

Conduct long- and short-term planning of improvement activities. Balance or align issues and improvements, considering existing goals and constraints.

Consists of long-term decisions (concerning [Improvement-Approaches]) and short-term planning.

5.14. Report-Structure

When you examine (audit, review) systems, as proposed in Analyze, you often need to prepare a report for the management in charge.

This practice proposes a generic report structure you might use in preparing such documents.

Table 6. Report Structure
Chapter Description


formal stuff, like disclaimer, references to contractual documents, table of contents, licence, change history etc.

Management Summary

1, at most 2 page summary


describe the goals of the review/audit.

Review Approach

brief description how the review was conducted, outline the activities or actions performed.


outline which stakeholders participated, in what form, at that time


in order of importance or priority, list and explain your findings

Proposed Actions


Appendix: Sources

list your sources and references, e.g. documents, source-code, interview protocols, issue-trackers, websites etc.

Appendix: The Team

briefly introduce the review team and explain their role in the review.

  • Slide or Write to decide, wether you really need to prepare a written report.

  • Traceability, to ensure you have proper sources for all important issues.

5.15. Separate-Cause-From-Effect

5.15.1. Intent

Explicitly differentiate between symptom (effect) and cause:

  • Identify root causes of symptoms, problems or issues

  • Trace a problem to its origins

5.15.2. Description

Under discussion!

5.16. Slide or Write

In every review you will face the question of how to deliver and present the results to the customer. Will you write a long and formal report document or is a set of presentation slides adequate and sufficient?

5.16.1. Intent

  • Consider format and structure of the review report early.

  • Ensure that you share a common vision with your customer about the preparation of results .

  • Remind contractual agreements and formal requirements, especially if someone might take offence by your report.

5.16.2. Description

There are two common ways to deliver review results:

  • As a formal document (Word, PDF, etc.)

  • As a collection of slides (Powerpoint, Keynote, etc.) and a presentation

In general it is recommended to write the review results down in a well structured document. This form is suitable to contain a lot of details and background information, so that it is easy e.g. to trace back a recommendation to a stakeholder interview. A written document can (and should) contain all information needed to understand the review starting position, targets, approach and findings, without spoken words and additional explanations. If the results shall supplementary be presented to some audiences it is easy to create purposeful slides from this document.

A set of Powerpoint slides as only result is adequate if the customer has been closely involved in the review process and is mainly interested in the outcome and if there will definitely be a presentation given to all relevant stakeholders. In this case the creation of slides with the most important bullet points might be quicker than the writing of detailed, well formulated text.

5.16.3. Experiences

In a review for a financial broker we agreed initially to deliver a detailed document with the results. When we were later asked to present the outcomes to two different audiences (engineers and management) it was quite easy to create specific slides for both of them from the ~ 40 pages of documentation.

In another case we planned to present out review finding in one big meeting and so we wrapped all findings into briefly and concise slides. Later some executives who missed the meeting complained that they needed some spoken explanations to understand the presentation document. We spent much more time in subsequently writing out the background information as if we had worked on a result document from beginning on.

5.17. Traceability

Maintain references to the origin of problems or issues: Remember who told you about a problem, in which documents you found issues and in what version of the source you identified risks or faults.

5.17.1. Intent

When discussing problems, some stakeholders will question or doubt your findings (see pattern Expect Denial). Keeping thorough references to the orgins or original sources of major findings keeps eventual critics in check.

5.17.2. Description

(To be done)

5.17.3. Experiences

Some anti-experiences that happened when we neglected traceability:

Stakeholder questioned some of our findings - we could not immediately trace those findings back to an original source (i.e. an interview protocoll, a particular file/version of source code). These stakeholders immediately suspected all our findings, not only the one or two in question.

Please keep in mind that a lack of traceability, especially for disputed findings or problems, might lead to serious loss of credibility.

On the other hand, maintaining detailed references is a time-consuming task. You easily spend hours with (rather trivial) bookkeeping activities, instead of identifying new and exciting problems.

5.17.4. Applicability

Apply traceability whenever you identify problems or issues

  • which might discredit or offend one important stakeholder,

  • which seriously impact parts of the underlying organization, company or business unit,

  • that carry huge financial, technical or organizational risks or penalties.

Short rule: The more expensive or dangerous, the more traceability you need.

5.18. Widen Your Options

Before taking decisions it’s often a good idea to widen your decision space, look for additional options. Sometimes it’s not only "yes-or-no" decisions, but a spectrum of additional options are available - at least if you allow your brain to deviate from conventional path or your own preliminary conclusions.

6. Pattern index

This chapter contains an alphabetic list of all patterns, practices and methods with a short description and links to the explanation.

  1. Anticorruption Layer

    Isolate clients from internal changes of suby-systems or modules. The original definition:

    Create an isolating layer to provide clients with functionality in terms of their own domain model. The layer talks to the other system through its existing interface, requiring little or no modification to the other system. Internally, the layer translates in both directions as necessary between the two models. (Domain Driven Design, page 365)

    — Eric Evans

    Category: Improve

  2. Architectural-Understanding

    Document relevant structures, concepts, decisions, interfaces etc. of the [System] to locate issues, risks and opportunities for improvement. See [arc42] and View Based Understanding. Category: Cross-Cutting Practices and Patterns

  3. Architecture-Backlog

    Keep a prioritized list of improvement tasks (remedies) with their as a backlog, parallel to the (regular) feature backlog. Category: Improve

  4. Assertions

    Use assertions to verify preconditions and to make a program fail early when something goes fundamentally wrong. Category: Improve

  5. Atam

    Systematic approach to find architectural risks, tradeoffs (compromises) and sensitivity points. Category: Analyze

  6. Automated Tests

    Introduce automated tests to verify correctness or runtime behavior. Unit-, integration-, acceptance-, load- or database-tests are well-known specialisations of this. Category: Improve

  7. Branch For Improvement

    Introduce distinct branches in your version control system to reflect improvements. Category: Improve

  8. Capture Quality Requirements

    Part of Atam, Capture and document specific quality requirements. Specialisation of Requirements-Analysis. Category: Analyze

  9. Change by Extension

    Enable efficient change by creating new components instead of modifying existing ones. Category: Improve

  10. Change by Copy

    Isolate competing change necessity by copying and allowing the copies to evolve independently. Also known as [Change-Via-Split] Category: Improve

  11. Change Via Split

    Isolate competing change necessity by copying and allowing the copies to evolve independently. Also known as [Change-Via-Split] Category: Improve

  12. [collect-opportunities-for-improvement]

    Keep a list of possible and potential measures, remedies, tactics, strategies for improvements. Regularly match those to your collection of issues. Category: Cross-Cutting Practices and Patterns

  13. Collect Issues

    Keep a list of problems, issues and risks. Regularly match those to your collection of possible remedies. Category: Cross-Cutting Practices and Patterns

  14. Context-Analysis

    Analyse external interfaces for risk, technology, business value and other factors. Category: Analyze

  15. Data-Analysis

    Analyse and inspect the data created and manipulated by the system for its content, structure, quantity and size. Category: Analyze

  16. Debugging

    Identify the source of a bug or misbehavior by observing the detailed flow of execution, e.g. stepwise execution of program statements. Usually supported by debugger. Specialisation of Root Cause Analysis. Category: Analyze

  17. [Deprecate-Obsolete-Parts]

    Category: Improve

  18. Development-Process-Analysis

    Analyse and inspect the development process (as documented or described by stakeholders) for appropriateness, problems or problem-areas. Category: Analyze

  19. Documentation-Analysis

    Analyse existing documentation for availability, correctness, actuality, problems or problem-areas. Category: Analyze

  20. Estimate Feature Value

    Estimate the (monetary) value of a given feature, so you can compare features of the system with each other. Category: Evaluate

  21. Estimate in Interval

    Estimation differs from measurement in its inherent uncertainty. Therefore, estimate in intervals, giving lower and upper bounds. The difference between the two shows your confidence in the estimate. Low (relative) difference means high confidence. Category: Evaluate

  22. Estimate Issue Cost

    Find out how much a given issue costs in units of money or effort in a period of time or for every occurence. Category: Evaluate

  23. Estimate Improvement Cost

    Determine how much a specific improvement (a set of actions taken to eliminate or reduce a specific issue or problem) is likely to cost (in money and/or effort). Category: Evaluate

  24. Expect Denial Some people will oppose your findings, will whitewash or sugarcoat issues, problems or root causes. Regardless on how careful you prepared your analysis, they will try to diminish or attack your findings. Category: Cross-Cutting Practices and Patterns

  25. Explicit Assumption

    Compensate missing facts (especially requirements, goals, estimates, opinions) by explicit (usually written) assumptions about those facts. Category: Cross-Cutting Practices and Patterns

  26. Extract Reusable Component

    Extract code from an existing system to create a reusable component. See [SERIOUS-Refactoring], page 95. Category: Improve

  27. Fail Fast

    Identify quality issues as early as possible and aim to fix them. Category: Cross-Cutting Practices and Patterns

  28. Fast Feedback

    Evaluate the quality of work artifacts and processes as early as possible. Enables teams to apply corrective actions or take countermeasures as early as possible. Category: Cross-Cutting Practices and Patterns

  29. Front End Switch

    Route front-end requests to either new or old backend systems, depending on their nature, content-negotiation or other request criteria. This is especially helpful to support [Never-Change-Running-System]. Category: Improve

  30. Group Improvement Actions

    Collect several improvement actions, which can or shall be applied or implemented together. Category: Improve

  31. Handle If Else Chains

    Refactor nested if-then-else structures for improved understandability. Can be seen as a specialisation of [Remove-Nested-Control-Structures]. Category: Improve

  32. [Hierarchical-Quality-Model]

    Decompose the overall goal of "high quality" into more detailed and precise requirements, finally resulting in a tree-like structure. See Atam and [Quality-Requirements]. Category: Analyze

  33. Impact Analysis:: Determine what impact (in code, concepts and the organization) a specific action (e.g. refactoring) will or might have. Category: Cross-Cutting Practices and Patterns

  34. Improve Code Layout

    Making code easier to read results in better understandability. Category: Improve

  35. Improve Logging

    Making runtime analysis easier with meaningful logs. This includes decentralized log analysis as well as well-structured log levels, markers and log message phrasing. Category: Improve

  36. Improvement Backlog

    Keep a backlog of possible improvements, remedies, tactics or strategies. Category: Cross-Cutting Practices and Patterns

  37. Infrastructure-Analysis

    Analyze the technical infrastructure of the [System], e.g. with respect to time and resource consumption or creation. Part of Runtime-Analysis. Category: Analyze

  38. Instrument System

    Instrument either the executable or the source code to make assumtions explicit and expand on Runtime-Analysis and [Runtime-Artifact-Analysis]. Category: Analyze

  39. Interface Segregation Principle

    Reduce coupling between clients and service provider. Category: Improve

  40. Introduce Boy Scout Rule

    Establish a policy to perform certain structural improvements each time an artifact (source code, configuration, documents etc.) is changed. Usable in situations where a [Refactoring-Plan] is not feasible or in addition to such a plan. Category: Improve

  41. Introduce Layering

    Introduce layers within the source code to improve separation of concern. It’s common to have at least a business layer and an interface layer - the latter for both user- and programatic interfaces. See Uncle Bob’s Clean Architecture for a short summary. Category: Improve

  42. Isolate Changes

    Introduce interfaces and intra-system borders, so that changes cannot propagate to other areas. Category: Improve

  43. Issue List

    Keep a list or collection or issues (problems, risks) - together with an appropriate amount of description and evaluation. Category: Cross-Cutting Practices and Patterns

  44. Issue-Tracker-Analysis

    Analyse entries from issue-tracker to identify critical areas, components or stakeholders. Category: Analyze

  45. Keep Data Toss Code

    A strategy to improve systems, keeping the data created with the (old) systems as foundation for a new one. Also described as Bridge-to-the-New-Town (by Wolfgang Keller). This is the opposite of [Never-Change-Running-System]. Category: Improve

  46. Manage Complex Client Dependencies With Facade

    Simplify the interaction of a client with a set of service components. Category: Improve

  47. Measure

    Gather various metrics and visualize them on dashboards in order to make your system behavior more predictable and assumed coincidences explainable. Examples of such metrics are thread pool saturation, number of failed logins, requests per second but also number of successful orders today, amount-of-time-spent-debugging-this-component, code-metrics, amount-of-effort-needed-for-feature…​ Category: Improve

  48. Migrate Data

    Transform existing data from one structure or representation into another by keeping its original intent or semantic intact. Category: Improve

  49. Mikado-Method

    Coordinated refactoring effort, described in the Mikado-book. Category: Improve

  50. Natural Death

    Keep old system running and only retire it once all objects contained reach end of life according to their life cycle. Category: Improve

  51. Never Change Running System

    To minimize risks, you should try to refrain from changes to existing (working) code - as every change inevitably introduces new risks or even bugs. Category: Improve

  52. Never Rewrite Running System

    Joel Spolsky arguments, never to rewrite a system from scratch, as you will likely make many new mistake and won’t generate much added value. Category: Improve

  53. Organizational-Analysis

    Analyse and inspect organization(s) responsible for the system. Category: Analyze

  54. Outside-in Interfaces

    Modularize system aligned to (existing) external interfaces. Category: Improve

  55. Pre Interview Questionnaire

    Prior to interviewing stakeholders, present them with a written questionnaire, so they can reflect in advance. A specialisation of Questionnaire. Category: Analyze

  56. Qualitative Analysis

    Analyze which quality goals of the [System] are at risk and which are met by the current implementation. Needs concrete [Quality-Requirements]. See [Atam] Category: Analyze

  57. Quality Driven Software Architecture (QDSA)

    Derive (technical, structural or process-related) decisions based upon detailed quality requirements. QDSA requires explicit quality requirements. Category: Improve

  58. Quantitative-Analysis

    Measure artifacts or processes within the system, e.g. source code. For example, see Runtime-Analysis and Static Code Analysis. Category: Analyze

  59. Questionnaire

    Written collection of questions presented to stakeholders. Can be addendum, preparation or replacement of Stakeholder Interview. Category: Analyze

  60. Refactoring

    Source code transformation that does not change functionality of system. See [Fowler-Refactoring]. Category: Improve

  61. Refactoring Plan

    The route of refactoring, as discussed within the development team. This plan should always be visible to every team member. Category: Improve

  62. Requirements-Analysis

    Analyze and document (current) requirements: required features and required constraints Category: Analyze

  63. Remove Nested Control Structures

    Re-structure code so that deeply nested or complicated control structures are replaced by semantically identical versions. Special case of [Refactoring], similar to [Untangle-Code]. Often performed by reducing complexity and especially cyclomatic complexity. When reducing code complexity one needs to make sure we’re not exchanging inner/ method/ cyclomatic complexity by outer/ design or runtime complexity. Category: Improve

  64. Report-Structure

    A generic structure for written audit or review reports, usually following an Analyze phase. See Slide or Write. Category: Cross-Cutting Practices and Patterns.

  65. Root Cause Analysis

    Find the evil at the bottom: Explicitely differentiate between symptom and cause: Identify root causes of symptoms, problems or issues. Category: Analyze

  66. Runtime-Analysis

    Analyze the runtime behavior of the [System], e.g. with respect to time and resource consumption or creation. See [Profiling], [Performance-Analysis] and [Runtime-Artifact-Analysis]. Category: Analyze

  67. Sample For Improvement

    Provide concrete code example for typical improvement situations, so that developers can improve existing code easily. Category: Improve

  68. Schedule Work

    Schedule refactoring or improvement work, so that all (business and technical) stakeholders know about them. Category: Improve

  69. Separate-Cause-From-Effect

  70. Software Archeology

    Understand software by analysing its source code, usually in absence of other documentation or knowledge sources. Category: Analyze

  71. Stakeholder Analysis

    Find out which people, roles, organizational units or organizations have interests in the [System]. Category: Analyze

  72. Stakeholder Interview

    Conduct personal interviews with key persons of the [System] or associated processes to identify, clarify or discuss potential issues and remedies. Category: Analyze

  73. Stakeholder Specific Communication

    Communicate with stakeholders by actively applying their specific or favored terminology and/or communication channels. Category: Cross-Cutting Practices and Patterns

  74. Static Code Analysis

    Analyse source code to identify building blocks and their dependencies, determine complexity, coupling, cohesion and other structural properties. Category: Analyze

  75. Structural Analysis

    Analyze the static structures (e.g. building block structure) of the [System], e.g. package or module dependencies, runtime- and/or deployment dependencies. See the more specific Static Code Analysis, Context-Analysis and Data-Analysis. Category: Analyze

  76. Systematically prepare and take decisions by finding appropriate options, check assumptions, overcome emotion and prepare to be wrong. See Decisive (by C+D Heath). Category: Cross-Cutting Practices and Patterns

  77. Take What They Mean, Not What They Say

    Natural language has the risk, that semantics on the senders' side differs from semantics of the receiver: People simply misunderstand each other because meaning of words differ between people. Pattern provided by Phillip Ghadir (who is too humble to claim this discovery) Category: Analyze

  78. Toggle Feature

    Simultaneously support evolved, competing or conflicting features at runtime by toggling feature flags. Category: Improve, see also:

  79. Traceability

    Maintain references to the origin of problems or issues: Remember who told you about a problem, in which documents you found issues and in what version of the source you identified risks or faults. Category: Cross-Cutting Practices and Patterns

  80. Untangle Code

    Remove unneccessary complications in code, e.g. nested structures, dependencies, dead-code, duplicate-code etc. See [Remove-Nested-Control-Structures]. Special case of [Refactoring]. Category: Improve

  81. Use Case Cluster

    Understand system functionality by grouping functionality into clusters to reduce complexity. Category: Analyze

  82. User-Analysis

    Get an overview of user-categories or -groups, their goals, requirements and expectations. Find out about issues users have with the system. Related to Stakeholder Analysis, Context-Analysis and Requirements-Analysis. Category: Analyze

  83. Use Invariants To Kill Zombies

    Use Invariants to make sure that you can kill Zombies safely. If code seems to be “dead” — meaning that it supposedly isn’t called anymore — but no one dares to remove it from the codebase, the introduction of invariants can provide reliable feedback on whether it is safe to remove the code or not. Category: Improve

  84. View Based Understanding

    Create architectural views (mainly building block view) to understand and communicate code structure. Category: Analyze

Appendix A: Domain Model

Within the systematic improvement we consider and manipulate several typical kinds of information, entities.

For a more pragmatic description, please see the Common Terminology section

aim42 domain model
Figure 30. aim42 domain terminology - detailed


Root cause of an Issue, in contrast to a symptom.


(inherits from) Issue

is real source of

one or many Issues.



Technical or organizational constraints, restraining management, design, implementation or operation of the System.


the System, associated Processes or Organization.


Any (hopefully written) information about the systems, its goals, requirements, architecture, implementation, operation or management.


What does the Organization or Stakeholder expect from the System, why does the System exist anyway.


Structure and kind of hardware required to develop, test and operate the System.


Any remedy, opportunity, tactic or strategy to improve the System by resolving one or several Issues.

modifies or creates


is remedy for

the System.


(partially or complete) one or several Issues


Any problem, error, fault, risk, suboptimal situation or their causes within the System, Processes or Organization related to it (e.g. management, operational, development, administrative or organizational activities).


how often does the Issue occur?

resolved by

one or several Improvements.


The organization or entity responsible or owning the System.

source of



Processes, conventions or activities for developing, maintaining, operating or managing the System.

source of




Indicator that the Risk is occuring and turning into a problem.

is an

(inherits from) Issue, but not occurred yet.


All source code and configuration that make up the System under improvement. Hopefully stored in version-control.

is an

Issue, but not occurred yet.


People or roles interested or participating in the System or any of its associated Processes.

belong to

the Organization responsible or owning the System.

knows / informs about

Issues and/or Improvements. Stakeholders often know about existing problems and opportunities for improvements.


The system under improvement, consisting of Software, Hardware and Documentation.

managed and affected by



the System or aspects of it by Improvements

suffers from


complies with

one or several Goals.

consists of

Software, Configuration, Hardware and Documentation.

Appendix B: Bibliography

  • William J. Brown: AntiPatterns: Refactoring Software, Architecture and Projects in Crisis, John Wiley & Sons, 1998 — a tried and true work on things that tend to go wrong in software development and other projects.

  • [arc42] arc42 - Resources for Software Architects. Practical template, liberal licence. Available in a variety of formats, see German website or English website.

  • [Agans-Debugging] David J. Agans: Debugging: The 9 Indispensable Rules for Finding Even the Mose Elusive Software and Hardware Problems. Amacom Press, 2002. Although most developers take "debugging skills" for granted, they sometimes spend too much time tracking too little bugs.

  • [Annett-Legacy] Robert Annett: Working with Legacy Systems: A practical guide to the real systems we inherit. Leanpub Publishing.

  • [SEI-ATAM] Architecture Tradeoff Analysis Method. Software Engineering Institute, Carnegie Mellon University.

  • [Berglung-AfferentCoupling] Tim Berglund (GitHub) on Complexity Theory and Software Development. Look at slide 73ff on afferent coupling - and keep that in mind for your own refactorings.

  • [Bass09] Len Bass et.al.: Software Architecture in Practice. Addison-Wesley, 2. Edition 2009.

  • [Big-Ball-Of-Mud] Brian Foote and Joseph Yoder, Big Ball of Mud - very influentual paper from the fourth conference on Patterns languages of Program Design, PLoP97

  • [BISBAL] BISBAL, J. et.al.: A Survey of Research into Legacy System Migration. Technical Report TCD-CS-1997-01, Computer Science Department, Trinity College Dublin, 1997. http://citeseerx.ist.psu.edu/viewdoc/summary?doi=

  • [Bommer-Wartung] Christoph Bommer, M. Spindler, V. Barr: Softwarewartung: Grundlagen, Management und Wartungstechniken. (in German) dpunkt Verlag, 2008. Interesting treatment of categories of software systems and their respective need for maintenance and evolution. Authors quote studies from Lehman and Belady from the 1970’s.

  • [Boy-Scout-Rule-article] The Boy Scout Rule, see http://programmer.97things.oreilly.com/wiki/index.php/The_Boy_Scout_Rule

  • [Brodie-Stonebraker] Brodie, M. and Stonebraker, M: Migrating Legacy Systems: Gateway, Interfaces & the Incremental Approach; Morgan Kaufmann 1995.

  • [Clements-ATAM] Paul Clements et.al.: Evaluating Software Architecture - Methods and Case Studies. Addison-Wesley, 2001. Detailed overview of ATAM (and other evaluation methods).

  • [Campbell14] Ann Campbell et. al: SonarQube in Action. Manning Publications, 2014. Great introduction to the flexible, multi-language code-analysis toolkit.

  • [ERDLE] ERDLE, C.: Management von Softwaresystemen – Legacy Migrationsstrategien. Seminar an der TU München, Fakultät Informatik, 2005. http://www4.in.tum.de/lehre/seminare/hs/WS0506/mvs/files/Ausarbeitung_Erdle.pdf

  • [Feathers] Michael Feathers: Working Effectively with Legacy Code. Prentice Hall, 2005. The author claims "Code without tests is bad code". So true…​

  • [Fowler-Refactoring] Martin Fowler: Refactoring. Addision-Wesley. Addision-Wesley, 1999. See also refactoring.com

  • [Freemann] Steve Freeman, Nat Pryce: Growing Object Oriented Software By Tests. Addison-Wesley, 2010.

  • [heath-decisive] Chip and Dan Heath: Decisive: How to make better choices in life and work. Crown Publishing / Random House Books, 2013. A practical and pragmatic guide to decision making (both preparing and taking them) - not specific to software. They describe four pillars of systematic decision making, which we adopted for our crosscutting practice Systematic-Decisions.

  • [Henney] Kevlin Henney: 97 Things Every Programmer Should Know. O’Reilly Media, 2010, ISBN 0596809484, also available online

  • [Hunt-Archeology] Andy Hunt, Dave Thomas: Software Archeology, IEEE Software, March/April 2002

  • [Impact-Mapping] Gojko Adzic: Impact Mapping. Making a Big Impact With Software Products and Projects.

  • [ISO-9126] ISO 9126 Quality Model: Hierarchical model for software quality, consisting of six major quality topics (functionality, reliability, usability, efficiency, maintainability and portability).

  • [ISO-14764] ISO/IEC 14764 Standard on Software Maintenance:2006. For a brief overview, see Wikepedia-entry on ISO-14764.

  • [ISO-25010] ISO/IEC 25010 Systems and software Quality Requirements and Evaluation (SQuaRE) — System and software quality models. ISO-Standard model for software quality. Superseeds [ISO-9126] and categorizes software quality into 8 characteristics: functional suitability, reliability, efficiency, operability, security, compatibility, maintainability, transferability. See ISO-25010 website.

  • [Keller-Migration] Wolfgang Keller: The Bridge to the New Town - A Legacy System Migration Pattern. EuroPLoP 2000, ISBN 3-87940-775-4

  • [Lippert-Refactoring] M.Lippert, S.Roock: Refactoring in Large Software Projects: Performing Complex Restructurings Successfully, Wiley 2006

  • [Martin-CleanCode] Robert Martin: Clean Code - A Handbook of Agile Software Craftmanship. Prentice Hall, 2009. A detailed writeup of how (object-oriented) code should look like. Lots of things we like.

  • [Mikado] Ola Elnestam, Daniel Brolund: The Mikado Method. Manning, 2014. Describes a method to morphing software from bad to better state. Quote from the book: “It helps us visualize, plan, and perform business-value-focused improvements over several iterations and increments of work, without ever having a broken codebase”

  • [Moyer-Archeology] Brian Moyer: Software Archeology

  • [Object-Oriented-Software-Construction] Bertrand Meyer: Object-Oriented Software Construction, Prentice Hall (September 1994), ISBN-13: 978-0136290490
    One of those old books which is has influenced many a software but is actually known to few.

  • [Ogawa-Evolution] Michael Ogawa: Software Evolution Storylines. Available as research paper, open-source code and online. Visualizes interactions between developers in software systems

  • [OORP] Serge Demeyer et. al: Object-Oriented Reengineering Patterns. A pattern-based approach to re-engineer object-oriented legacy systems. It contains a wealth of improvement-patterns, some named slightly different than their aim42-brethren.

  • [Quality-Requirements] (Free) Examples of Practical Software Quality Requirements.

  • [SERIOUS] Software Evolution, Refactoring, Improvement of Operational & Usable Systems. ITEA / EUREKA research project. Completed in 2008, holds a fairly large number of deliverables. Too bad, some of the result websites are down…​

  • [SERIOUS-Refactoring] SERIOUS Refactoring Handbook.

  • [SERIOUS-Methods] SERIOUS project. Overview and evaluation of design and refactoring methods

  • [Software-Evolution] Journal of Software: Evolution and Process. Academic journal on software evolution and maintenance.

  • [SonarQube] SonarQube is an free and open platform to measure manage code quality, lots of plugins for a variety of programming languages, plugins for different metrics and checks. SonarQube can track results over time - showing the history of code quality for software systems.

  • [Spolsky-NeverRewrite] Joel Spolsky: Things You Should Never Do, Part-I

Appendix C: Glossary


Architecture Improvement Method.


Architecture Tradeoff Analysis Method. Extensively described in Clemens-2001 and online by the SEI, briefly described as aim42 pattern.


Loss of functionality under defined (stated) conditions.


Software Engineering Institute at the Carnegie Mellon University. A federally funded research and development institute, sponsored by the US Departement of Defense.


The system to be improved - often a single software system, but it might be a complex combination of hardware, software and organizational aspects. Systems in our sense consists of:

  • software, usually with corresponding data structures and data

  • required infrastructure software, like operating system, database, UI-frameworks, middleware etc.

  • required hardware infrastructure, like processors, storage facilities, network, routers etc.

  • associated development processes, like requirements engineering, architecture, implementation, version- and configuration management, build- and deployment

  • associated administration and operation processes or procedures

  • associated organizational processes, like budgeting, HR, controlling, management etc.

  • associated external systems, like data-/event providers or consumers.

and maybe even more :-)


(of an improvement or remedy). Approximately -1 times the cost of the associated issue(s). If an improvement solves only part of an issue, value estimation becomes much harder.

Appendix D: Organizational Stuff

The Team

  • Gernot Starke (innoQ Fellow, project founder): setup, patterns, practices

  • Alex Heusingfeld (innoQ): hero-of-the-build, Travis-CI integration

  • Peter Hruschka (Atlantic Systems Guild): reviews + comments, especially to the intricacies of the Domain Model.

  • Christine Koppelt (innoQ): improvement-patterns

  • Michael Mahlberg (Consulting Guild): patterns and practices

  • Burkhard Neppert (innoQ): review, method

  • Roland Schimmack: review, practices and patterns, bugfixes

  • Oliver Tigges (innoQ): patterns and practices

  • Stefan Tilkov (innoQ): maintenance and evolution patterns

  • Tammo van Lessen (innoQ): improvement patterns, technical debt contribution

  • (what are you waiting for - join us!)

Comments and suggestions by Markus Harrer, Phillip Ghadir - and numerous (anonymous) project-teams from all around the IT-world.


aim42 is free to use, similar to many open-source software systems.

For practical reasons we decided to apply the Creative Commons Attributions Sharealike 4.0 license.

Copyright 2012-2014 the original author (Gernot Starke) or authors and contributors.

Licensed under the Creative Commons Attributions Sharealike (the "License"); You may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software and documentation distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Contribute to aim42.org

This content is open source! The source is hosted under the aim42 organization on GitHub.

If you want to help by improving upon it, fork the project, revise the content, then send a pull request.


aim42 currently provides a method guide, the asciidoc sources are hosted at GitHub under the aim42 organization.


Look over our open issues, pick one, fork the repository and resolve the issue. Send over a pull request!



Mailing list

Due to excessive spam, we closed our (human-managed) mailing list - therefore you have to stick to issues (see above) to get in contact with the aim42 team.


open an issue (see above) and test our reactivity…​

(due to increased spam we had to remove the convenient mailto links, sorry)

Appendix E: Asciidoc Help

To facilitate contributions we summarize the AsciiDoc (respectively AsciiDoctor) features used within this guide.

We found the following information especially helpful for learning asciidoc:



explanation creates a link to the explanation of some-anchor.

can use the cross-reference in a list, but not with labelled-list:

  1. pattern name labelled-list with cross-reference does not work

  2. cross-references need to be boldface-formatted manualy

https://github.com/aim42/aim42/issues/20[an external resource]

Link to files / artifacts in new browser window/tab:



here we explain 'some-anchor' topic…​

<<some-anchor,explanation>> creates a link to the explanation of some-anchor.

can use the cross-reference in a list, but not with labelled-list:

. <<some-anchor, pattern name>>  labelled-list with cross-reference does not work
. *<<some-anchor, cross-references>>* need to be boldface-formatted manualy

here we explain 'some-anchor' topic...

Images and Diagrams

Including images is quite easy:

image::aim42-logo.png["alternate-text", title="caption-example"]
Figure 31. caption-example

You can even reference these images, like see figure caption-example:

...see figure <<caption-example>>

I currently have no clue how to reference figure-numbers (their counter), though…​


* first entry
* one more
  • first entry

  • one more


Special annotations rendering nicely:

NOTE: Admonition paragraphs call attention to special words of advice

WARNING: a warning

CAUTION: be careful

IMPORTANT: must be really worth reading

TIP: maybe some practice report
Admonition paragraphs call attention to special words of advice
a warning
be careful
must be really worth reading
maybe some practice report
Multi-line admonitions blocks need special treatment:

they need a block-masquerading (e.g. by "--" at the beginning and end.

The result is rendered nicely.

renders as follows:

Multi-line admonitions blocks need special treatment:

they need a block-masquerading (e.g. by "--" at the beginning and end.

The result is rendered nicely.

Files and Directories

Files are included with the "include" directive:



Some attributes are useful, e.g.


will insert the last modification data (here: 2016-07-28)


In case you need a footnote - that’s easy too:

A statement.footnote:[the text of this footnote, usually rendered at the end of the document.]


Sometimes it can be useful to write smaller text.

... useful to write [small]#smaller text#.

Appendix F: How to add a new pattern or practice

  1. Add the pattern to the related section in analyze.adoc, evaluate.adoc or improve.adoc Use the exact spelling (e.g. including dashes) you intend to use in the pattern description

  2. Add the pattern to the pattern catalog in pattern-index.adoc

  3. Entries in the pattern-index which currently don’t have a detailed description in their own file are preceded with an anchor, like [[the-exact-name]]

  4. If you describe a pattern or practice in detail, create a new file with the appropriate name and the .adoc extension under the pattern subdirectory.

  5. At the beginning of that new file, include the anchor, like [[the-exact-name]]. See below for an example.

    === The Exact Name
    (write your pattern description here...)
  6. Add an include statement below the pattern overview in analyze.adoc, evaluate.adoc or improve.adoc

  7. In the pattern index, create a reference, like _<<the-exact-name>>

1. The original authors of ATAM call it an evaluation method, whereas aim42 classifies ATAM to belong to the category of analysis practices.