Improving the consistency and usefulness of architecture descriptions: Guidelines for architects

The need to support software architecture evolution has been well recognized, even more since the rise of agile methods. However, assuring the conformance between architecture descriptions and the implementation remains challenging. Inconsistencies emanate among multiple architecture descriptions, and between architecture descriptions and code. As a consequence, architecture descriptions are not always trusted and used to the extent that their authors wish for. In this paper, we present two surveys with 93 and 72 participants to examine architectural inconsistencies, with a focus on how they evolve over time and can be mitigated using practical guidelines. We identified the importance of capturing emerging elements to keep the architecture description consistent with the implementation, and consider the current-state and future-state architecture separately. Consequences of inconsistencies typically arise at later stages, especially if an architecture description concerns multiple teams. Our guidelines suggest to limit the upfront architecture to stable decisions, while paying attention to concerns that matter across team borders. In the ideal case, companies should aim to integrate architects into the teams to capture emerging aspects with time