Method Reference

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

The phases are:

The ATAM method:

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:

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 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 workshop-based collection of quality requirements has been described by [Clements-ATAM].

We distinguish the following terms in context analysis:

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

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. Figure 10, “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.

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.

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:

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

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:

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

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

Under discussion!

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

Under discussion!

Look for:

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

Infrastructure analysis is associated to the more general Section 2.3.21, “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:

It helps to measure runtime behavior agains expected or required values, for example processing time and memory consumption. Section 2.3.10, “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 Section 2.3.28, “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.

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

Under discussion!

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 Section 2.3.25, “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:

In real life, since the mechanisms of instrumentation varies 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 cross-cutting 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.

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

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

Under discussion!

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

Work-in-progress: collecting ideas and currently doing research, therefore still chaotic document

Section 2.3.29, “Bus factor”

Evaluate and track the welfare and health of a software development and operation organization or community such that additional project cost can be avoided or somehow managed.

Organization, coordination and cooperation are critical forces behind software development and operation. Through well-thought protocols and cooperation guidelines, software architects, developers as much as entire organizations try to orchestrate proper coordination and cooperation but many times such attempts are burdened by sub-optimal organisational decisions, e.g., the adoption of a process model that is not compatible with developers and operators’ background and mindset or even collaborating with an organization that does not and cannot share the same values of the organization in question. These circumstances often result in additional project cost in the form of recurrent delays, condescending behaviour or worse.

Evaluating these circumstances together, trying to minimise their impact on software development and the quality of resulting software products is currently object of intensive study.

The goal for social debt in the next few years of research is that of reaching a crisp definition that contains the essential traits of social debt which can be refined into practical operationalizations for use by software engineering professionals in need of knowing more about their organizational structure and the properties/cost trade-off that structure currently reflects.

As previously mentioned, we found three recurrent series of circumstances in which architecture decisions and the process of architecting reportedly generated social debt.

All Cross-cutting patterns relate to the circumstances defined above.

Find out (analyze):

Use qualitative analysis to support in the following situations:

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

Under discussion!

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 a group of stakeholders. This can lead to more work for you as interviewer, but will also lead to better interview results.

Mix open and closed questions:

Include a "Comments/Remarks" section at the end of the questionnaire, so stakeholders can comment on topics you did not consider in advance. The Section 2.3.16, “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:

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

Identify issues that could let become the current project a huge disaster.

In software projects, post-mortems are often used to learn from a failed projects with the goal to avoid the identified problems in the future. But why wait for so long?

In a pre-mortem workshop, stakeholders are imaging that they are living some months or years in the future to analyse their current project that had been failed miserably. They are explicitly encouraged to speak about the main points that did go wrong from the future’s perspective.

The organization of the workshop for a running software project can be done as follows:

A pre-mortem session combines the potential of negative thinking and creative thinking in a relaxed environment. Stakeholders are rewarded for the identification of issues instead of being played down or marked as naysayers. This leads to a huge amount of input from all kind of participants that would otherwise be quite regarding potential problems. The viewpoint from the future frees participants from thinking just in short terms and provides.

Pre-mortem is a complementary method to interviews with stakeholders, that is very efficient due to the focused scenario and multi-perspective format.

In the evaluate phase, the identified reasons can be a great starting point for further analysis.

Additionally, identified reasons from a pre-mortem session can be seen as potential risks and thus be included and tracked in the project’s risk management.

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:

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 me to stay on track, cover a multitude of topics, even when I conducted several interviews consecutively.

I usually printed out 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

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

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

Under discussion!

Look for and document:

Explicitly differentiate between symptom and cause:

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.

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

You can eliminate the cause.

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

Understand software by examining existing source code.

You have to understand a system with:

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:

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.

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

Conduct a Section 2.3.23, “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, choose a quiet location, make sure nobody can overhear your interviews.

If possible, send out a stakeholder- or role-specific Section 2.3.16, “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.:

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.

Static Analysis can serve two purposes:

Use source code analysis tools to analyse static properties of the system’s source code, e.g. the following:

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

Find out the real meaning/intention of stakeholders

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

Therefore: what people mean/want/need is sometimes not what they say. This is due either to

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 Section 5.11, “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 thanks to Phillip Ghadir (who is too humble to claim this discovery) for giving this pattern its name.

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

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

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

Use view-based-understanding when:

Improve the structure of a system or its documentation so that the organisation is not at risk if certain key people leave.

In an ideal world, the whole team owns the all code and anybody can safely change anything. Often this is not the case, because

Usually, a team has already a good grasp on which parts of the system certain developers own the knowledge almost completely. It is vital to get some numbers through mining repository data, e.g. if you think that dev A is the only one knowing about some security code, then you can analyze the commit history of the security package. Adam Tornhill gives a lot of ideas and also code snippets on how to do that in his book "Your Code As a Crime Scene". What he does is looking at the changed lines of a package over all the commits of a certain time frame. If a large amount (e.g. >80%) of those commits is coming from a single developers, you should act.

It is often easy to spot and verify problematic knowledge islands, but getting rid of them (e.g. pair programming, documentation, automation) is really hard, because the developers living on that knowledge island usually want to protect it.

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

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.

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 Section 5.9, “Explicit Assumption”.

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

Finding out the cost of an issue usually requires estimation or guessing, so there are uncertainty and probability 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’s effort.

If you multiply with (an approximated or averaged) wage, you get problem cost.

A big bang rewrite replaces an old system with a new system with one big bang deployment. The new system is developed from scratch. The opposite approach would be an incremental replacement, where individual parts get replaced step by step.

Positive:

Negative:

Big bang replacement of medium and large systems have many risks, which shouldn’t be taken lightheaded. You need to make sure that you understand and communicate the risks and that risk, cost and benefit are worth it.

You should consider a rewrite (not necessarily big bang) for the following reasons:

A big bang approach is possible, if you cannot or want to incrementally replace the system for the following reasons:

Things you should never do.

Software-Migration with incremental steps to avoid or reduce the risks coming along with the Big Bang approach.

Chicken Little was already described back in the 1990s of the last century by Michael L. Brodie and Michael Stonebreaker and is explained in their great book 'Migrating Legacy Systems' [1].

The name of this approach originates from a Walt Disney cartoon, where the protagonist Chicken Little is a very young hero who saves all with his cautious & conservative character. These are also highly essential & invaluable qualities in software migration.

The name 'Cold Turkey' for a Big Bang migration was also introduced by Brodie and Stonebreaker, which is a synonym for cold detoxification and therefore clearly describes the dislike of the authors in this kind of migration.

The central idea of Chicken Little is to create a composite system consisting of the legacy system and the new target system. Incrementally, components of the legacy system are replaced with components of the target system. The legacy system thereby shrinks and the target system grows.

The composition is implemented through gateways. They transfer both reading and writing requests to the respectively other system. A gateway can be a forward or a reverse gateway. A forward gateway is integrated into the legacy system and routes requests to the target system. A reverse gateway is part of the target system routing to the legacy system.

Brodie and Stonebreaker define Chicken Little as 11 steps. Each step is applied for every increment of the migration. An increment can be a use case or a bounded context. The execution of these 11 steps can be in any order and parallel; steps can be omitted.

Use this approach (or the main ideas) when you need to migrate in a safe and incremental way. It is highly recommended for mission-critical systems.

Software migration is not easy, and one will need patience and endurance. Migration projects can last several years. For that, a strong team is required.

Incremental migration

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

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:

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.

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.

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

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.

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 Coordinator 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) are the only way to extract the legacy data. Once the functionality has been ascertained, the component can be redeveloped 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 coordinated 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 coordinator.

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

Data migration method without the need of 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 an 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 temporarily store. A Data Access Allocator (DAA) decides, if a request has to be send to temp store (for already changed data) or to the original database. With the help of a Chrysalizer (a 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 initial 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 will be no change in between the two stores anymore. 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 execute 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 massive amount of data. Also it can be very expensive to implement the DAA.

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 Section 4.7.1, “Big Bang Approach”, 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:

The system has several distinct (usually nearly disjunct) user groups. For each of these groups, slightly different business rules, processes or other requirements hold.

Maintain and evolve a few smaller systems, instead of one big monolith. Reduce time-to-market, work in smaller teams that individually become more focussed.

Steps 4 and 5 might be interchanged or done in parallel.

Whenever a legacy system servers more than one homogeneous user group, this split approach might be appropriate.

The business processes for the various user groups need to be sufficiently different from one another - otherwise splits would merely create duplicate functionality.

Divide a legacy system into different functional domains and replace those step by step.

Rewriting an old system with the Section 4.7.1, “Big Bang Approach” is a risky endeavor. It is harder than you might think at the beginning.

An alternative way is to gradually create a new system around the edges of the old, letting it grow slowly over several years until the old system is strangled. The most important reason to consider a strangler application over a cut-over rewrite is reduced risk (it might cost more to do a strangler, but that’s the price of risk reduction) [1].

Paul Hammont depicts the strangler approach as follows [2]:

He discusses two ways of achieving the goal of moving from the (red) old system to the (blue) new system:

Deciding to go for the first strategy means that you can still keep your business happy because you are still able to deliver new features. However, this approach will take longer than the second one.

Paul Hammant recommends the following practices [2]:

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 replace their own or third-party software without affecting the clients of this interface.

The original definition [Evans03, p. 365]:

Here are some real-life experiences:

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

Intention to change or replace a cohesive piece of code with a lot of incoming (afferent) dependencies. A common example is replacing homegrown ORM or plain SQL with a standard tool or exchanging a logging library for another with incompatible interfaces.

Incrementally replace part of the system with a new implementation.

This method is also known as "Branch by Abstraction" and a smiliar technique that goes under the names "Parallel Change" or "Expand and Contract" exists, where the abstraction step is skipped and callers are migrated to a new method/object immediately.

This approach works best when it is used in combination with Section 4.10.6, “Introduce Boy Scout Rule”.

Too many of these half-performed incremental refactorings will leave your code base in a mess. You still need to finish, what you start.

Your team is familiar with and embraces Trunk-Based development.

http://continuousdelivery.com/2011/05/make-large-scale-changes-incrementally-with-branch-by-abstraction/
http://paulhammant.com/blog/branch_by_abstraction.html
http://www.alwaysagileconsulting.com/application-pattern-verify-branch-by-abstraction/
http://martinfowler.com/bliki/BranchByAbstraction.html
https://printhelloworld.de/posts/refactoring-in-baby-steps/
https://www.branchbyabstraction.com/

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:

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.

This pattern should always be considered.

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

Enable cross-cutting architectural improvement even if it is not feasible to change the whole codebase.

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

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.

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

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:

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 get drown in numbers.

This pattern should always be considered.

Provide a safe approach in situations where it seems to dangerous to delete code or whole modules from a huge system because Section 2.3.25, “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:

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 web services are not so far out of the question.

If a huge number of deployments is possible without problems it can also be feasible to deescalate 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.

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.

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:

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.

Docs-As-Code is a documentation approach that raises developer-related documentation to the same importance as source code.

Developer-related documentation of software systems is often neglected. In many situations, it’s not the lack of ideas for meaningful content that prevents documentation but the way developers have to do it: Separate programs have to be started and other work processes have to be followed. These and many more other distractions lead to long context switch times.

The additional effort could be a reason for a rather negative attitude towards documentation on the developer side. As a result, the developer’s documentation is neglected and becomes obsolete with the time until it can no longer be used for anything at all. Unfortunately, missing or outdated documentation has negative consequences for the understandability of the entire software system.

The core idea of Docs-As-Code is to use the same tools and processes for creating documentation as for creating source code. This ensures that there are no high costs for context switches.

There are a few practices that ensure that the acceptance of documentation increases in software development teams:

The seamless integration of documentation creation into the software development process means that there are no longer any obstacles for software developers to document necessary facts. By reusing the tools and processes, the documentation work gets the same importance as the writing of source code. Work on documentation becomes as visible as newly written code. The automated creation of documentation artifacts or websites makes the current status of the documentation more clear to other stakeholders such as product owners or project managers.

When documentation and source code are in the very same code repository, developers can be kind of forced to update the documentation when they write new features or update existing ones. With the help of pull requests and code review techniques, it can be checked very quickly if necessary documentation updates were made.

Apply this pattern when there is a clear lack of documentation. Start by defining the minimum required scope of documentation for new features (e. g. take some parts of the arc42 documentation template as a guidance if developers complain that they don’t know what to document).

Show the documentation in sprint reviews to make non-technical developers aware of the newly created content.

Can lead to grumbling at the beginning (at the latest when the first pull request is declined due to missing documentation).