A Few New Concepts - Architectonic Mantra, Design Retrospective, Shared Context, Natural Order of Refactoring

Recently, several named concepts have evolved in my mind, or maybe I just understood them well. Here are a few notes that I consider an alpha draft ;-)

Architectonic Mantra

What happens practically in every project is the drifting of architecture. After several months, few team members can clearly define which operations should be performed by controllers, domain objects, facades, or services. Over time, the responsibilities of these classes get mixed, making it increasingly difficult to develop the system. The only option in this case is the so-called architectonic mantra, a variation on the broken record technique known from communication psychology. It involves continuously reminding the team of the main blocks in the architecture and their responsibilities. I also suggest that teams introduce regular meetings (once a month or once per sprint) called Design Retrospective, where the team:

• Reminds the architectonic mantra;
• Analyzes situations where it’s unclear where specific classes, operations, or fields should be located based on recent project activities;
• Collects cases of architectural drift and creates a “repair program”;
• Makes decisions about conscious restructuring of the architecture (though this happens less frequently).

Shared Context

This isn’t about design or architectural patterns, but about communication. As Kent Beck once said, “Most problems in projects arise because someone didn’t tell someone else something.” Agile advocates see the source of problems in relay race, or passing work between people. The issue is that when passing products (documentation, code, requirements, etc.) from one person (or group) to another, the context that led to the product creation is often not transferred, mistakenly deemed irrelevant. I assert that it is crucial.

Recently, I was in such a situation. One person conducted a preliminary analysis of requirements and created a basic system model (domain model). We were to analyze this model, but without the context (certain reflections, conclusions, information, micro-decisions) formed in the mind of the person who created it, it was difficult to evaluate its correctness beyond UML correctness. I call such cases a lack of shared context.

We eventually started to jointly analyze project requirements (User Stories) and build the model from scratch together. We arrived at a similar model (with subtle differences), but during the “joint work,” a shared context emerged (i.e., a unified understanding and insights). Shared context enables more accurate decision-making and more effective continuation of work, which is why close collaboration is emphasized heavily in Agile.

One warning: Do not overwhelm anyone with the product of your work, expecting them to understand it well. At the very least, review and explain it with them. Better yet, develop it together. It will save you and them a lot of work, especially avoiding many communication distortions that generate unnecessary work.

Natural Order of Refactoring

This topic warrants a separate article, but here is a brief description.

The concept of systematizing the refactoring process from the lowest level of abstraction to the highest has been crystallizing in my mind—a natural way of evolutionary design development. The idea is to start with the simplest solution, refactoring if needed at various abstraction levels in a certain order. Here’s the hierarchy of transformations (beginning with low-level ones):

• 0. Transformations (triangulations - if using TDD)
• 1. Compose method refactoring - breaking a complex method into a series of calls to component methods at the same abstraction level, transforming one block of code into several methods.
• 2. Extract class, Extract interface, Move method, Move field refactoring based on class responsibility analysis.
• 3. Refactoring to design patterns - introducing design patterns for variability in projects.
• 4. Refactoring to architectural patterns - adapting architectural assumptions as required by changing system requirements.

Agile System Modeling Heuristics

How to reach an initial model that allows starting implementation while avoiding basic mistakes of unthought architecture? When and how to plan architecture? Here’s a proposal for an agile “path,” a mix of Scrum/Agile practices, ICONIX, and our BNS experiences:

1. Define (if not yet done) User Stories/Epics, covering about 80% of the system.
2. Analyze interactions with external systems for additional requirements.
3. Determine priorities and what will enter the Release (deployment version).
4. During User Stories analysis, build the domain model focusing on class names and relationships.
5. Extract system services (operations) from User Stories, phrasing them in business language.
6. Determine the complexity of operations.
7. Choose the architecture direction based on the domain model.
8. Select complex and risky services for analysis.
9. Integrate architecture into technology, partition services accordingly.
10. Analyze 1-2 User Stories (implementation concept) to verify concept assumptions.
11. Implement selected 1-2 User Stories to verify concepts.
12. Define the Architectonic Mantra.
13. Continue incremental project realization.

Related Offtopic

“Architecture is not about drawings, diagrams, or system connections, but a deep understanding of the domain and context you’re working with. Forget about UML, forget about super-tools supporting your design, engage thinking. Put most of your energy into understanding the domain, which will lead you to appropriate design constructs.”

Consider exploring Domain Driven Design and Lean Architecture concepts.

(Text translated and moved from original old blog automatically by AI. May contain inaccuracies.)