6 signals that your architecture is not visible enough

With more than 26 years of experience, as a consultant, I help organizations in the .NET space to professionalize their entire software development efforts, from idea to production. During such visits, I get to scrutinize their development practices, quality standards, design principles, the tools they use, their deployment pipeline, the team dynamics, the requirements process and much more. In this series of short posts, I’ll share some of the most common pain points I run into.

In my last post in this series, I’ve been diving into the depths of coding practices that have a smell. This time, I’d like to focus on the availability and discoverability of technical information about architecture. Some teams are more then willing to write documentation, but what’s lacking is clarity on where to find that documentation, how it relates to the architecture and how up-to-date it still is. Here are some consequences of that.

• It is often not obvious where in the system some piece of functionality is implemented. This is particularly an issue when the code is structured along the technical aspects of the system instead of aligning with functional modules. This is frequently caused by developers that don’t understand the internal boundaries and architectural seams of the system, either because they are too focused on the details, or because the architecture itself has been obfuscated.
• And if you look at the architecture from the code’s perspective, you should be able to deduce…