Abstract

Abstract
Creating and using software documentation presents numerous challenges, namely in what concerns the expression of knowledge structures, consistency maintenance and classification. Adaptive Software Artifacts is a flexible approach to expressing structured contents that tackles these concerns, and that is being realized in the context of a Software Forge. Copyright © 2013 by the Association for Computing Machinery, Inc. (ACM).

Abstract

Abstract
Monitoring a system over time is as important as ever with the increasing use of cloud-native software architectures. This paper expands the set of patterns published in a previous paper (Liveness Endpoint, Readiness Endpoint and Synthetic Testing) with two solutions for supporting teams in diagnosing occurring issues — Deployment Tracking and Exception Tracking. These patterns advise tracking relevant events that occur in the system. The Deployment Tracking pattern provides means to limit the sources of an anomaly, and the Exception Tracking pattern makes a specific class of anomalies visible so that a team can act on them. Both patterns help practitioners identify the root cause of an issue, which is instrumental in fixing it. They can help even less experienced professionals to improve monitoring processes, and reduce the mean time to resolve problems with their application. These patterns draw on documented industry best practices and existing tools. In order to help the reader find other patterns that supplement the ones suggested in this study, relations to already-existing monitoring patterns are also examined. © 2023 Copyright held by the owner/author(s).

Abstract
Background: Approaches to documenting the software patterns of a system can support intentionally and manually documenting them or automatically extracting them from the source code. Some of the approaches that we review do not maintain proximity between code and documentation. Others do not update the documentation after the code is changed. All of them present a low level of liveness. Approach: This work proposes an approach to improve the understandability of a software system by documenting the design patterns it uses. We regard the creation and the documentation of software as part of the same process and attempt to streamline the two activities. We achieve this by increasing the feedback about the pattern instances present in the code, during development-i.e., by increasing liveness. Moreover, our approach maintains proximity between code and documentation and allows us to visualize the pattern instances under the same environment. We developed a prototype-DesignPatternDoc-for IntelliJ IDEA that continuously identifies pattern instances in the code, suggests them to the developer, generates the respective pattern-instance documentation, and enables live editing and visualization of that documentation. Results: To evaluate this approach, we conducted a controlled experiment with 21 novice developers. We asked participants to complete three tasks that involved understanding and evolving small software systems-up to six classes and 100 lines of code-and recorded the duration and the number of context switches. The results show that our approach helps developers spend less time understanding and documenting a software system when compared to using tools with a lower degree of liveness. Additionally, embedding documentation in the IDE and maintaining it close to the source code reduces context switching significantly.

Abstract