aim42/aim42

public repository for the "architecture improvement method reference"

Architecture Improvement Method

Software Evolution, Maintenance and Improvement - Done Right!

aim42 is collection of practices and patterns to support software evolution, maintenance, evolution and improvement of software systems.

aim42 divides change activities in three distinct phases:

• analyze issues, risks, problems, symptoms and technical debt within software (and their organisations).
• evaluate those issues, identify root-causes and remedies, prioritize.
• improve by applying appropriate remedies, strategies and tactics.

aim42 has been founded by Gernot Starke, is supported by innoQ Deutschland GmbH and is licenced under the liberal Creative Commons Sharealike 4.0 licence.

Learn more

• our project homepage gives an overview
• the online method reference provides all (currently available) details (this is our main artifact - currently under intensive development). The method reference is automatically updated with every commit pushed to the central repository by Travis-CI.

Contribute

• found mistakes or ommissions: create an issue
• have ideas: fork the repository and create a pull request. You need a basic understanding of Git for this.
• follow us on twitter

We write the content in AsciiDoc and build with Gradle.

As of September 2017, we removed the AsciiDoc help from the aim42 guide, you can find it here, under the arc42 organization.

Current Status

Repository Organization

Top-Level

(Original drawn with draw.io, source located in /graphics/meta/aim42-repo-structure.xml)

Graphics

Both diagrams created with (desktop-version of) draw.io, source located in /graphics/meta/aim42-repo-structure.xml)

aim42's Issues

gh-page don't update upon commit

hhm - although branch gh-pages is current, it is not displayed at aim42.github.io...

Estimate-in-Intervalls (new practice for evaluation phase)

describe intervall-based estimation as (one) foundation for evaluation.

• intervall size determines confidence in estimate
• need to ensure real value lies within intervall

write pattern "static analysis"

Write Practice on Decision-Taking

D& C Heath

Introduce 'about' section

current situation

When a visitor enters http://aim42.github.io/ he has no information what this page is about or what the abbreviation "aim" actually stands for.

suggestion

Introduce a short 3-4 sentences long 'about' section at the beginning of the document linking to http://aim42.org/about/ (cough which isn't finished either, yet. cough) or to http://aim42.org/ so the document is put into context.

add "glossary" (appendix)

where we explain

• abbreviations (e.g. ATAM, SuD)
• explanations of important terms (e.g. our domain entities, like risk, problem, cost etc.)
• explanation and links to terms from literature (e.g. technical debt)

beautify (method-guide) website (awestruct, custom theme)

Add Pattern "Slow down to go fast" to cross cutting patterns

Avoid to confuse operational speed (moving quickly) with strategic speed (reducing the time it takes to deliver value).

interesting read can be nicely translated to our context.

Include "architectural feature" from SAFE-framework

imho the notion of "architectural feature" or "architectural epic" from the SAFE (scaled agile framework) will fit seamlessly into aim42:

http://scaledagileframework.com/, especially
http://scaledagileframework.com/architectural-feature/

unit-test all internal references

to check misspelled links and anchors

Clarify Goals for Phase

Analyze: find issue and understand system, document. RCA in here, also debugging

Evaluate: Just that, prioritize

differentiate "fail-fast" and "fast-feedback"

as discussed f2f, fail-fast might be a slightly different (and specialize) practice than the more general "fast-feedback".

imho "fail-fast" could also be named "abort-quickly" or "abort-asap", as it could be more concerned with "projects" than with smaller units...

check out new github-pages features, decide which to use

Alex,
I know you're currently "down-under-workload", but I'd love your opinion:

https://github.com/blog/1833-github-pages-3

best,
Gernot

expand "code review" or "code reading" practice

some nice hints on infoQ:
http://java.dzone.com/articles/code-review-best-practices
(by Vlad Mihalcea)

Code review is a great software instrument and you should definitely use it to improve the quality of your code. But like any other tool, it may be misused sometimes. That’s why I came up with a list of best practices to guide you when reviewing your peers’ code.

Code review is not testing: Code review is a developer-to-developer business and it doesn’t involve any testing. Code review should check if the task requirements are met in the cleanest possible way.
You don’t tell what to code review: The same way you don’t tell a tester what to test, you should never tell your peer what to review. The magic of peer review comes from your peer own perspective on the current task design and implementation. Two minds are always better than one.
You should always check all changes: Bugs may be hidden anywhere and you should search for them diligently. To have the whole picture you need to go through all changes.
Requirements first: Requirements are the most important driving force. After all that’s what the customer is paying for. If the current changes are suboptimal you need to reopen the issue. If you happen to spot other code sections that need to be refactored you should create new issues instead of reopening the current one. The “single responsibility principle” applies to tasks as well as to coding.
One-to-many activity: If you can’t make sure you grasp the code change intention it’s safer to ask somebody else to review it further.
A way of learning: Code review is a great learning technique especially on large projects. Ideally you should become familiar with every aspect of your project, but if the project is too large you can at least specialize in multiple modules.

Happy code reviewing!

Add pattern for better logging and runtime metrics under "Improve"

Name is still a TODO. Basic idea: Good logging, good metrics (e.g. thread/db pool saturation) can help significantly to find potential problems before they occur. Also if it turns out that analysis based on log files is impossible and thus very difficult. This can be eased by improving logging. An anti-pattern is however if devs start to do trial and error with debug logging on the production system.

clarify "find solution approaches"

as cross-cutting task

elaborate "Expect-Denial"

@stilkov said:
this could be elaborated to more fine-grained aspects, such as

• attacking the analysis itself,
• the evaluation (in terms of cost of the problem and/or cost of the solution),
• the feasibility of a proposed remedy (technically or in terms of resources).

Some counter-measures would be great too.

write pattern "extract-reusable-component"

add "prepare and take decisions"

Agree on a name (symbol) for the "system under improvement"

Up until now we use all kinds of symbols to identify the system we're trying to improve with the application of aim42. Sometimes its "the software" sometimes "the system" sometime simply "system" etc.
More often than not, the system under improvement is only part of a bigger landscape and a differentiation between the general terms and the part of the systems that's under improvement would be helpful (at least for me).
Is "system under improvement" (SUI) acceptable? Or does it come across to technical? Or to close to the SUT (the 'system under test' from the testing world).

rename "determine problem cost"

into "estimate...", more consistent with other eval practices

add "prepare and take decisions"

New Pattern: Instrument System

Instrument either the executable or the source code to make assumtions explicit and expand on runtime analysis and runtime artifact analysis.
This can be achieved by employing aspect weavers, pre-processors, dependency-injection frameworks and by a number of other techniques.

Add pattern "Introduce boy scout rule"

add "prepare and take decisions"

setup (rake or gradle) build process for github-pages

Alex called for github -> Alex can create the build :-)

What is technical debt? (Warning: Meta Question)

Actually the question is not really, what technical debt is ;-)
I reference the concept in Introduce Boy Scout Rule, Gernot references it in the introduction and long term goal.

How do we want to handle things like this?
Technical debt is a well known concept to some and has been wildly discussed - on the other hand it is also subject to a huge amount of semantic diffusion so it might be appropriate to have a section on the concept itself.

So here are the resulting questions:
a) (concrete) Do we want to have our own description of the concept technical debt?
b) (meta) If we would like to have such a description - where would we put it (and others like it)
c) (concrete) IF a.false() { which article(s) to link to? And where to put the links? }

Suggestions for c)

• http://www.infoq.com/news/2008/08/tech-debt-wkshp
• Ward Cunningham's video
• The c2 explanation
• Martin Fowler's interpretation
• All of the above ;-)

Add pattern "Fail Fast" to cross cutting patterns

Avoid technical debt by monitoring the quality of code or other artifacts constantly and provide counter measures or pull the plug as early as possible.

Peers reviews, code reviews, early tests will help find situations where efforts go into the wrong direction.

Travis build error after submitting pull request for document.

See: https://travis-ci.org/aim42/aim42/builds/18934719

I'm afraid I don't yet understand what happens travis-wise when I create a pull-request.
The error-log states that

"No X11 DISPLAY variable was set, but this program performed an operation which requires it." 

Furthermore the error indicates that the build tried to push to pg-pages - which probably should not happen with pull request before they are merged, should it?

create custom-css for pattern-names

I'd like pattern- and practice names to be set in small-caps.

In a first (short) experiment I couldn't get the css-3 font-property
small-caps working...

Pointers that may help:

• http://asciidoctor.org/docs/produce-custom-themes-using-asciidoctor-stylesheet-factory/
• http://asciidoctor.org/docs/user-manual/#custom-styling-with-attributes
• http://www.w3schools.com/cssref/pr_font_font-variant.asp

New Pattern: Kill Zombies with Invariants

Use Invariants to make sure that you can kill Zombies safely.

write a sanity-check-with-report

producing html output, so that authors know what

• links are broken,
• bookmarks ("references") are missing
• images are missing or badly named

(as the junit output is not well-suited to identify missing stuff, even with
hamcrest-matchers it's awful)

Limit Feature by Client

Is this the same as applying the "interface segregation principle"?

explain term "SuD"

which is referenced several times, but not explained (link target does not exist)

describe "debugging"

I wrote a column for "JavaMagazin" about effective debugging - take practices out of that one...

enhance phase description

integrate ISO 25010 (capture quality requirements)

the currently referenced ISO 9126 is awesome but deprecated...
imho the replacement is way to complicated - but current :-(

need to add appropriate references and hints how this new one works...

Expand "root cause analysis"

Add specific techniques

• 5 whys
• Ishikawa diagram
• cause and effect diagram (Weinberg)

Write pattern "sheparding the architecture"

• enable development team to conduct improvement
• increase methodical, technical or organizational capability of team or organization

Convert OOP-2014 talk on business-relation of architecture into aim42 pattern

as you proposed in the ECSA-2014 submission... some detailed info on topics like NPV and its relation to technical stuff...

enhance build to generate pdf version

pdf needs to be

• generated (either directly via asciidoc or via docbook-backend)
• copied to download-location (please suggest proper location/URL)
• download might be referenced from aim42.org site

setup mail list for (internal) discussion of contributors

Was mir noch ein bisschen fehlt - und auch Burkhard gestern vermisst hat - ist die geeignete Diskussionsplattform. Wenn wir das über GitHub machen ist jede Diskussion direkt öffentlich, per E-Mail ist aber auch nicht immer optimal.

Cross-Check our patterns/practices with "OORP" from Nierstrasz et al

http://scg.unibe.ch/download/oorp/ formerly was a book, is now free (CC-licenced).

@feststelltaste reminded me we should cross-check (see his mail below):

(======== snip ============)
über Twitter bin ich auf aim42 aufmerksam geworden. Ich finde es sehr gut, dass sich in diesem Bereich wieder mehr tut!

Ich wollte euch unbedingt auf ein ähnliches "Projekt" aus dem Jahr 2008 hinweisen: Das Buch "Object-Oriented Reengineering Patterns" von Demeyer u.a. (http://scg.unibe.ch/download/oorp/). Hier ist ein musterorientiertes Vorgehensmodell für das Reengineering von Legacy Systems beschrieben. Das Besondere daran ist, dass die Inhalte dieses Buchs ebenfalls unter einer Creative Commons Lizenz (der CC BY-SA 3.0) veröffentlicht wurden. Außerdem sind diese Patterns teils bereits gereviewt (u.a. durch Kent Beck, Ralph Johnson und Martin Fowler, siehe "Foreword" und "Acknowledgments").

Ich habe auch kurz die beiden Patternkataloge (oberflächlich) verglichen (links: Pattern aim42, rechts: Pattern OORP, Zeichen: = gleich, ~ ungefähr, > beinhaltet)

1. Explicit Assumption ~ 5.1 Tie Code and Questions
2. Impact Analysis ~ 2.4 Most Valuable First
3. Outside-in Interfaces = 7.8 Present the Right Interface
4. Profiling ~ 7.12 Use Profiler Before Optimizing
5. Root-Cause Analysis = 2.5 Fix Problems, Not Symptoms
6. Sample for Improvement ~ 7.2 Build Confidence
7. Software Archeology : 5.5 Learn from the Past
8. Stakeholder Interview > 2.4 Most Valuable First
9. Stakeholder Interview > 3.1 Chat with the Maintainers
10. Untangle Code > 9.1 Move Behavior Close to Data
11. Untangle Code > 9.2 Eliminate Navigation Code
12. Untangle Code > 9.3 Split Up God Class
13. View-Based Understanding : 4.2 Speculate about Design

Es wäre doch schade, wenn aim42 das Rad komplett neuerfinden würde, da es bereits eine solide Basis für einen musterorientierten Softwaresanierungsprozess gibt. Ich persönlich fände eine Zusammenarbeit zwischen den beiden Autorengruppen extrem gewinnbringend für die "Softwaresanierungs-Community".
(======== snap ============)

rename "never change running system"

OTigges schrieb: "Ich bin z.B. über das Pattern "Never-Change-Running-System” gestolpert, was ich für eine sehr gefährliche Aussage halte, wenn sie nicht im richtigen Kontext steht. Ich würde es entweder "Never-Rewrite-Running-System” o.ä. nennen, oder evtl. analog zu "Patterns & Pracitces” eine Kategorie ~ “Pitfalls & Biases” hinzufügen. Hier könnte man dann z.B. fragen, warum man so oft denkt, bei einem kompletten Neuschreiben würde alles viel schneller gehen."

create issues for most important patterns/practices

so that contributors get an overview of what is missing

write pattern "qualitative analysis" (ATAM-extract)

translate DE-version of pre-interview questionnaire to English

"Software Archeology" doesn't meet my expectations

Under that headline, I would have expected something that includes digging in the SCM history in order to understand why certain things are implemented that way. The description as it is right now would IMO fit better for the "Code Reading" pattern.

As an example: When I'm exploring some code I'm little familiar with, I tend to wonder why some things are implemented in a cumbersome way and aim to simplify it, e.g. being driven by the boy scout rule. However, especially with complex (say highly concurrent, transactional or security-related) systems, it turned out that the cumbersome way has been chosen for a good reason. Sometimes I found my intuitive/naive approach implemented but then replaced in the git history. At least for me, this was an important lesson to learn. 1. To assume that the author of a suspicious code line was not just too stupid. 2. To keep in mind, that there is another research dimension available, which is the time, that can help to understand why the code is as it is and why it has evolved in that way.

If you would agree with that pattern, I'm happy to come up with a pattern description.

explain internal and external quality

restrict build to index.adoc

currently all adoc files are compiled, thats massively redundant.