Comments or Issues: Where to Document Technical Debt?
Laerte Xavier, Jo\~ao Eduardo Montandon, Marco Tulio Valente
TL;DR
This study analyzes the factors influencing whether developers document technical debt via code comments or issues, providing guidelines based on a large dataset of GitHub projects.
Contribution
It offers the first large-scale empirical analysis comparing SATD in comments and issues, with 13 practical guidelines for choosing documentation methods.
Findings
Developers prefer comments for quick, small debts.
Issues are used for more complex or long-term debts.
Guidelines help improve technical debt documentation practices.
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.
Peer Reviews
No public reviews on file for this paper yet. If you reviewed it on a platform where reviews are public (OpenReview, ICLR, NeurIPS, ICML), you can paste yours below so the community can read it here.
Videos
No videos yet. Explain this paper in a talk, walkthrough, or lecture? Add one.