Comments or Issues: Where to Document Technical Debt?

Laerte Xavier,João Eduardo Montandon,Marco Tulio Valente

DOI: https://doi.org/10.1109/MS.2022.3170825

2024-08-27

Abstract:Self-Admitted Technical Debt (SATD) is a form of Technical Debt where developers document the debt using source code comments (SATD-C) or issues (SATD-I). However, it is still unclear the circumstances that drive developers to choose one or another. In this paper, we survey authors of both types of debts using a large-scale dataset containing 74K SATD-C and 20K SATD-I instances, extracted from 190 GitHub projects. As a result, we provide 13 guidelines to support developers to decide when to use comments or issues to report Technical Debt.

Software Engineering

What problem does this paper attempt to address?

The problem that this paper attempts to solve is: **What are the driving factors for developers to choose to use source code comments (Self - Admitted Technical Debt in Comments, SATD - C) or issues in the issue - tracking system (Self - Admitted Technical Debt in Issues, SATD - I) when recording technical debt (Technical Debt, TD)?**

Specifically, through investigating and analyzing a large number of data sets, the paper aims to reveal the specific situations and reasons for developers to choose to record technical debt in the following two cases:
1. **Using source code comments (SATD - C)**: Developers add comments in the code to record technical debt.
2. **Using issues in the issue - tracking system (SATD - I)**: Developers create issues to record technical debt.

To answer this question, the authors carried out large - scale data collection and developer surveys. They extracted 74,306 SATD - C instances and 20,265 SATD - I instances from 190 GitHub projects and surveyed 8,082 developers who use both methods to record technical debt. Finally, by analyzing the answers of 59 developers, 13 guiding principles were proposed to help developers better decide when to use comments or issues to record technical debt.

These guiding principles are divided into two categories:
- **Six guiding principles on using comments to record technical debt (SATD - C)**
- **Seven guiding principles on using issues to record technical debt (SATD - I)**

In addition, the paper also discusses the situation of using these two strategies in combination, as well as the influence of different project scales and technical debt priorities on the choice of strategies.

### Main contributions
1. **Providing empirical evidence**: The research results provide developers with empirical references on how to choose comments or issues to record technical debt.
2. **Influencing practitioners**: The proposed guiding principles can directly help developers, project managers, etc. better manage technical debt.
3. **Promoting research**: It emphasizes the importance of considering comments and issues in empirical research in software engineering and provides new research directions for researchers.
4. **Educational significance**: It provides a set of best - practice guidelines for educators to teach how to correctly report technical debt.

### Conclusion
Through this research, the authors not only revealed the driving factors for developers to choose the way to record technical debt, but also provided valuable guidance for future research and practice.