From Architecture to Code: A Primer On How to Get it Right

It’s an old lament. While creating an enterprise or application architecture is great for a conceptual understanding of something, it would be even greater if that architecture could be used directly to move from the conceptual to the tangible.

In other words, to generate actual code.

Getting an architectural artifact translated into a practical system implementation has always been problematic, but it doesn’t have to be. In fact, The Open Architecture Framework Group (TOGAF) envisioned this when its development began in 1995. One of its founding precepts was that an architecture may be specified as either a “formal description of a system, or a detailed plan of the system at the component level to guide its implementation”, or as “the structure of components, their interrelationships, and the principles and guidelines governing their design and evolution over time.”

As with the practice of architecture itself, recognizing and using the right patterns for the problems at hand is all important. In the case of the practical application of architecture to code, it has always been more difficult to accomplish than it sounds. However, after multiple successful (and less than successful) projects to either refactor existing code to an architecture or build code directly from an architectural model, some patterns have emerged that can increase the probability of success. Broadly speaking, those patterns involve vision, communications, and time.

Vision

Many might recognize the aforementioned as the things that are most commonly in short demand on development projects, and they’d be right. However, with a little pattern recognition and some upfront planning, the path from architectural artifact to implemented code can be a successful one, prior experiences to the contrary.

The first pattern is vision, or more specifically, clarity of vision. One of the knocks on architectural artifacts is that they’re open for interpretation and modification, and while this is technically true, when it comes to code development that’s not helpful.

One way to think about it is to imagine a cube in three dimensions and how each side of the cube can look different. The cube in its entirety is the software solution, however each side of the cube can appear different depending on who is doing the looking – architect, developer, project manager, sponsor, etc.

That’s why it’s critically important that the architectural vision – including the systems and integration points within it – is crystal clear and that all parties involved in the development process have the same understanding of that vision. This can’t be overstated. This is where most attempts to use architectural artifacts for systems development goes awry – one person interprets the artifact one way, and another person a different way.

That happens of course, but this issue is often complicated when the architect is unavailable for clarification, or worse yet when an architect is not particularly approachable.

To avoid this, it’s well worth the investment in time to conduct “clarity of vision” sessions as part of the initial systems development process. A good architect will prioritize questions from developers and spend the necessary time to explain and reiterate the core architectural concepts.

Some issues can’t be helped, as in the case of a key architect or developer leaving the company mid-project. In this instance it’s important for the team to regroup and dedicate the time required to get everybody in synch with the ultimate vision.

Communication

The next pattern to pay attention to is communication. That’s a term that can mean different things to different people and teams on a project, so a quick branch back to the first pattern of clarity is helpful.

In our context communication means answering a relevant question in a time period that engenders the most value from the given answer. Unfortunately, when it comes to architecture communication is often a one and done. That is, an architect presents the overall vision and scope to a development team leaving the presentation deck behind for reference.

As the project progresses, developers, project managers, and even architects are moved on and off the original project team. By the time the third developer assigned to work on developing the integration code hits the desk, that original communication and vision is long gone. The developer is left with questions unanswered and must therefore make his or her own assumptions about coding in the context of the original vision.

This is a very common occurrence and it inevitably leads to a sub-optimized code base and system. Instead, what should happen is that regularly scheduled communications meetings should be baked into the overall project plan.

The frequency of the meetings is project-size dependent, but the idea is the same. During these meetings – which can and should be brief – the goal is to perform a quick overview and synch-up for any new members of the team. Questions are asked and answered, and as importantly, high-level decisions that have been made during the course of the project are documented and reviewed to provide context and direction. And while these meetings take a little time, the longer-term benefits of avoiding “architecture by default” are too great to be ignored for short-term expediency.

Time

The final pattern to focus on is often the toughest one: time. Time is a diminishing resource in any project, but the tradeoffs that more often than not get made have a direct and lasting impact on the ultimate success of projects. It just takes time – time to review and explain things, time to ramp up new developers, time to communicate effectively, time to ask questions, time to listen and adjust, time to document – and on and on.

Time is the pattern that gets shortchanged the most (its own disturbing pattern) and that almost always causes the greatest amount of damage to a project: the architecture is unfinished and is developed on the fly; new developers are brought into the project but don’t understand the big picture vision; the program manager is reassigned to another project. Because of time constraints all of this and more degrades the consistency of the effort and the quality of the product.

A common scenario is when project implementation dates loom. Project Leads are often pressured to deliver the product on time, and that often means cutting corners on coding that leads to a vision disconnect between the architecture and the codebase.

For example, a technical lead might start building the skeleton of a single page application when a question arises with the framework configuration. If the architect is not available to clarify the question within a reasonable amount of time (say 1-2 days), the time pressure on the project may cause the technical lead to make an assumption about the configuration from the architectural artifact.

If the assumption is incorrect, then voila, technical debt has been created. If it is clarified quickly it might not be an issue, but when this happens multiple times throughout the codebase of a project it creates a cascading effect of a sub-optimized codebase and architecture. That almost always leads to an unplanned and costly refactoring of code at some point in time that has not been built into the project timeline.

If there were an easy fix for this everybody would already be doing it. Things change during projects and those changes never adhere prescribed timelines. However, just as with a sound architectural approach, patterns can be created that help to manage time better and help to mitigate time surprises when they occur.

For example, keeping development teams’ small limits the time required to train and synch new developers. At the beginning of a project make the case for a small but powerful (generalists and specialists) team that can see the project through to completion.

While difficult, adhering to the aforementioned patterns and practices has a better chance of project success than not. In this context, project success manifests itself as fewer vision questions along the way, less refactoring of code thanks to crisper communications, and a less troublesome project implementation. And who knows, it may even be on time.

Originally published in
Information Management
Read the original article here.