Documenting architectural rationale using source code annotations: An exploratory study

11 pages•Published: September 26, 2019

Santiago Hyun Dorado and Julio Ariel Hurtado

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.

Keyphrases: architectural rationale documentation, software architecture, source code annotations

In: Frederick Harris, Sergiu Dascalu, Sharad Sharma and Rui Wu (editors). Proceedings of 28th International Conference on Software Engineering and Data Engineering, vol 64, pages 204-214.

Links:	https://easychair.org/publications/paper/pcP5
	https://doi.org/10.29007/f5md

BibTeX entry

@inproceedings{SEDE2019:Documenting_architectural_rationale_using,
  author    = {Santiago Hyun Dorado and Julio Ariel Hurtado},
  title     = {Documenting architectural rationale using source code annotations: An exploratory study},
  booktitle = {Proceedings of 28th International Conference on Software Engineering and Data Engineering},
  editor    = {Frederick Harris and Sergiu Dascalu and Sharad Sharma and Rui Wu},
  series    = {EPiC Series in Computing},
  volume    = {64},
  publisher = {EasyChair},
  bibsource = {EasyChair, https://easychair.org},
  issn      = {2398-7340},
  url       = {/publications/paper/pcP5},
  doi       = {10.29007/f5md},
  pages     = {204-214},
  year      = {2019}}

Download PDF Open PDF in browser