Logo
ScienceStack
Table of Contents
Fetching ...
Sign In

Comments or Issues: Where to Document Technical Debt?

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

TL;DR

This paper investigates where to document Self-Admitted Technical Debt (SATD) by comparing code comments (SATD-C) and issue-tracker entries (SATD-I). It collects a large-scale dataset from 190 GitHub projects (74K SATD-C, 20K SATD-I) and surveys 59 developers who authored both forms, using open-card sorting to extract 13 practical guidelines. The guidelines are split into six SATD-C recommendations, seven SATD-I recommendations, and a mixed-strategy approach for using both channels, with a cheat sheet and repository for replication. The work provides actionable guidance for practitioners and researchers on TD documentation, supports improved traceability and collaboration, and enables better empirical studies and tool support for detecting and managing SATD.

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.

Comments or Issues: Where to Document Technical Debt?

TL;DR

This paper investigates where to document Self-Admitted Technical Debt (SATD) by comparing code comments (SATD-C) and issue-tracker entries (SATD-I). It collects a large-scale dataset from 190 GitHub projects (74K SATD-C, 20K SATD-I) and surveys 59 developers who authored both forms, using open-card sorting to extract 13 practical guidelines. The guidelines are split into six SATD-C recommendations, seven SATD-I recommendations, and a mixed-strategy approach for using both channels, with a cheat sheet and repository for replication. The work provides actionable guidance for practitioners and researchers on TD documentation, supports improved traceability and collaboration, and enables better empirical studies and tool support for detecting and managing SATD.

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.
Paper Structure (7 sections, 4 figures, 1 table)

This paper contains 7 sections, 4 figures, 1 table.

Table of Contents

  1. Introduction
  2. Study Design
  3. Proposed Guidelines
  4. Guidelines for Using Comments
  5. Guidelines for Using Issues
  6. Guidelines for Using Both Strategies
  7. Conclusion

Figures (4)

  • Figure 1: Example of SATD in microsoft/vscode issues.
  • Figure 2: Number of developers who reported each type of SATD.
  • Figure 3: Guidelines included in cockroachdb/cockroach wiki, after the discussion raised by our survey.
  • Figure 4: Technical Debt documentation guidelines.