Documenting architectural rationale using source code annotations: An exploratory study

Abstract

The architectural rationale is the documentation of the reasons why certain software design decisions are made that satisfy quality needs in a system. On many occasions this rationale is implicitly found in precise sentences of the system's documentation or the same source code, making it difficult to understand and make decisions on the maintenance phase, leading to a deviation and erosion of the architecture and therefore aging of the software. In this paper, we discuss the utility of a tool based on code annotations as an alternative to document the architectural rationale with the source code. For this, a quasi-experiment with local industry software engineers is done, in order to answer the research question: Does the source code annotations, with information about the architectural rationale, improves the software maintenance? The quasi-experiment is done with software engineers who know Java language and notions of software architectures. It included 3 tasks that involve changes to the architecture and its documentation. After the results were analyzed using the t-student test, concluding that the participants who use the annotations with information of the Architectural Rationale achieve a better understanding of the architecture and its Rationale than those using a traditional way for documenting the rationale(documents). However, the efficiency and effectiveness of maintenance time do not depend on the Rationale specification. With the same problem, the variation was due to the ability of individuals to develop software, but the documentation of the architecture, in general, was very important to be able to make the changes within the limits.