Automatic alignment of architecture and implementation

Honestly: Who actually enjoys manual reviews?

Authors: Ralph Dittmar, TR-Electronic GmbH, Thomas Eisenbarth, Axivion GmbH

Contribution – Embedded Software Engineering Congress 2018

The architecture, as the global structure of our software, is the foundation of our daily work. Therefore, it's essential that we engage with our architecture and not work against it: planning, testing, and evaluation are best achieved with the architecture in mind. However, developers traditionally work very meticulously on their software and thus easily lose sight of the bigger picture. That's why we at TR-Electronic have established an architecture review process, which saves us the effort of manual and often unpopular reviews and allows the architecture to become a living, breathing part of our daily work. We would like to share our experience and the results we've achieved, because adhering to the architecture has become second nature to us in our development process.

introduction

The architectural description of a software system allows for discussing the software at an abstract level and for analyzing, planning, and evaluating extensions to the software. For this to work well, the architecture must, among other things, be compatible with the implementation.

An architecture, as used here, describes the static structure of the system: Into which components is the system hierarchically divided? The relationships between the components describe the rules for the use of one component's interfaces by the other components. (see...). PDF, Fig. 1)

In the example shown in Figure 1, component K11 is allowed to access the interfaces of components K03 and K10. However, K05 is not allowed to access K03 directly.

Impact of an architecture description that is not suitable for implementation

An architecture description that is not suitable for implementation leads to the following effects:

• A gradual erosion process occurs, which intensifies over time.
• Understanding of the software is increasingly suffering.
• Respect for architecture is dwindling ("Why should I be the one who adheres to architecture...?").
• The planning becomes very detailed, as the rough structure no longer fits and is no longer suitable as a planning tool.

It therefore pays to keep the architecture and implementation aligned. Incidentally, this doesn't mean that an architecture, once created, must be followed slavishly. It can certainly happen that the idea behind the architecture changes and the implementation adapts to the revised idea, but the architecture description isn't updated accordingly. In that case, the solution is to correct the architecture description. However, one must be able to recognize when the implementation and the architecture description diverge.

Disadvantages of manual architecture review

The software has reached over 100 modules and continues to grow, so we're facing a significant problem of scale. A manual review process is inherently error-prone and time-consuming. Every change to the implementation or the architecture description requires repeated testing. The necessary manual effort is simply not feasible.

The automated architecture check, which runs concurrently with development as part of the build process, provides us with direct feedback. Project team members are "trained" in maintainability. Any architectural violations are always highlighted. Overall, this results in greater certainty for the developer: Have I completed my task structurally correctly? Furthermore, transparency for the project manager increases: Is my project structurally on track, or are adjustments necessary? The potential for human error is generally reduced.

Furthermore, we use the same components and modules in different applications, meaning that manually checking more than one application would be necessary. The automated, development-integrated check ensures that, after an implementation change, the implementation of all applications still conforms to the architecture description.

How the automatic architecture check works

The automated architecture check we use with the Axivion Bauhaus Suite based on hierarchical reflection models [1] has the following prerequisites:

• There is an architecture description (graph), in our case maintained in Enterprise Architect using a UML model.
• There is a rule for automatically detecting the relationship between implementation and architectural components. In this case, this is solved using a simple naming convention. This makes transferring architectural information to the implementation very easy and error-free for developers.

The dependencies between functions, variables, types, etc., are automatically derived from the implementation through static analysis. Checking one of these dependencies in the implementation against the architecture yields three possible results: convergence, absence, and divergence. In the case of convergence, the dependency found in the code matches the requirement of the architecture. An absence occurs when a dependency is required by the architecture but does not exist in the implementation. Finally, a divergence occurs when a dependency is found in the implementation that is not permitted by the architecture. (see...). PDF Fig. 2)

Figure 2 shows three components A, B, and C, each with a function a, b, and c as its implementation. Since A is allowed to have a relationship to B, and a(x) calls the function b(y), a convergence occurs. The relationship from B to C has no equivalent in the implementation, resulting in an absence. Finally, the call from c(z) to b(y) is a divergence, as the architecture does not permit it (it would require a relationship from C to B).

Discrepancies and omissions are considered violations. A violation can arise from a misunderstanding and a resulting deviation in the implementation. Furthermore, a violation can result from an architectural change that is not reflected in the architecture description, for example, if a plan change occurs during development: The implementation fits the architecture, but the architecture is no longer accurately represented in the architecture description.

Presentation and use of the results

The detected violations are displayed to the developer in detail in a web dashboard within the Axivion Bauhaus Suite. Overviews are available for the project manager, showing the history of violations and their total number during development. The dashboard also displays further erosion indicators, such as style violations, cyclical dependencies, and dead code, providing a comprehensive overview of all violations in the software under development.

Depending on the reason for the detected deviation, a developer can react immediately to the violation, for example, by updating the architecture (or notifying the architecture accordingly) or by redesigning the implementation as intended by the architecture. This leads to improved communication about the architecture and fosters learning. Furthermore, the interfaces required by the architecture and now controlled facilitate the distribution of work packages among multiple developers.

Project leaders and managers have the opportunity to assess the total amount of technical debt in the software and to keep business arguments in mind along with technical arguments, i.e., past debt and estimated costs of future development.

Consequences of the architecture review for processes and results

Working in a code-centric way opens up entirely new perspectives through the renewed emphasis on architecture and thus on the global relationships and structure of the software being developed. Long-term development is simplified in this way, as not every step requires reading the code. Because developers engage with the architecture beforehand, fewer violations occur during development, and impossible architectural requirements are identified and discussed earlier.

Conclusion

The architecture review has enabled us to shift to a more architecture-focused way of working. This results in fewer discrepancies between the architecture description and the implementation right from the start of development. Developers benefit from reduced workload, as there are fewer surprises during the implementation phase. The automated, development-integrated architecture review saves manual work that we would otherwise only be able to perform on a sample basis.

literature

[1] Koschke, Rainer; Simon, Daniel (2003): Hierarchical Reflection Models. In: WCRE 03: Proceedings of the 10th Working Conference on Reverse Engineering. pp. 36-45

authors

Ralph Dittmar Ralph Dittmar is a software developer at TR-Electronic GmbH and has been working on software projects for products certified up to SIL3/Ple since 2013. He has 15 years of experience as a software developer in the embedded systems field. Email: ralph.dittmar@tr-electronic.de

Thomas Eisenbarth Mr. Eisenbarth is the founder and managing director of Axivion GmbH, which develops and distributes analysis tools for software erosion protection. He has over 20 years of experience in software analysis and the testing of software architectures. Email: eisenbarth@axivion.com