Glossary
By the Glue Team
Technical debt tracking is the practice of systematically identifying, measuring, and monitoring technical debt in a codebase. Tracking makes debt visible, enables prioritization of debt paydown, and helps prevent debt from accumulating beyond management. Without tracking, debt grows invisibly until it becomes crisis.
Technical debt tracking involves:
Tracking is prerequisite to managing:
Visibility: Unmeasured debt is invisible. Teams don't realize how much debt they have until it becomes crisis ("Why are we so slow?"). Tracking makes debt visible before it becomes crisis.
Prevention: When teams see debt growing, they can prevent it. "We're adding 5 points of debt per sprint" creates pressure to prevent new debt. Without tracking, debt grows silently.
Prioritization: Not all debt is equal. Debt in frequently-changing code is worse than debt in stable code. Debt that blocks new features is worse than debt that doesn't. Tracking reveals which debt matters most.
Justification: "We should spend time on technical debt" is hard to justify without data. "Our test coverage is 20% and we have 500 cyclomatic complexity points" makes the case for investment.
Forecasting: Track velocity with and without debt paydown. Show how much slower features are because of debt. "Each feature takes 40% longer because of technical debt in authentication" makes business case for debt paydown.
Progress Verification: Teams commit to debt paydown ("This quarter we'll improve test coverage by 10%"). Tracking verifies progress. Without tracking, effort happens invisibly.
Code Complexity: Cyclomatic complexity measures decision points in code. Higher complexity = harder to understand and maintain. Track per module, per service, overall.
Test Coverage: What percentage of code is exercised by tests? Track overall and per module. 70%+ coverage on critical code is healthy.
Code Duplication: Duplicate code is debt. It's harder to maintain because changes must be made in multiple places. Identify duplicate logic and plan consolidation.
Documentation Gaps: Which critical systems lack documentation? Which decisions aren't recorded? What functions lack docstrings? Measure these gaps.
Dependency Age: When was each dependency last updated? Old dependencies indicate technical debt (security risk, missing optimizations). Track dependency age.
Testing Debt: What critical paths lack tests? What edge cases are untested? Maintain list of known gaps.
Architecture Debt: Which architectural decisions are proving suboptimal? Monolithic architecture that should be services. Synchronous systems that should be async. Track identified architectural debt.
Defect Rate: How many bugs are found in production? Decreasing defect rate as debt decreases is good metric.
Velocity: Track development velocity with and without debt paydown. Measure correlation between debt levels and velocity.
Tools-Based Tracking: Tools like SonarQube automatically track complexity, coverage, duplication. Metrics update continuously. Advantage: automatic, no manual work. Disadvantage: only measures what tools understand.
Manual Inventory: Spreadsheet listing known technical debt. High-level but requires discipline to maintain. Useful for architectural debt that tools can't measure.
Code Review Tracking: During code reviews, identify debt. Track identified issues. Advantage: captures context. Disadvantage: hard to quantify.
Combined Approach: Use tools for what they measure well (complexity, coverage). Use manual tracking for what they don't (design decisions, documentation gaps). Combine metrics.
Metrics Dashboard: Visualize metrics over time. Show trends. Are we improving or getting worse? Dashboard should be visible to team and leadership.
Complexity Metrics:
Testing Metrics:
Maintenance Metrics:
Dependency Metrics:
Quality Metrics:
Tracking alone doesn't prevent debt. Prevention requires:
Standards: Code review standards, test coverage requirements, documentation expectations. New code should meet standards.
Automation: Use linters, formatters, and automatic tests to enforce standards. Make it hard to commit debt.
Code Review: Reviewers should flag debt when introducing it. High debt changes should justify trade-offs.
Allocation: Reserve time for debt paydown. If debt can't be paid down, don't incur new debt.
Communication: When incurring debt, document why. "We're taking this shortcut to ship faster because..." This creates accountability.
Glue tracks technical debt by visualizing complexity, dependencies, and code patterns. This makes it visible to product and engineering teams, enabling prioritization and prevention.
"Tracking debt is overhead; we should just build." False. Time spent tracking prevents much larger waste (being slow due to unmanaged debt).
"Tracking tools can find all debt." False. Tools find measurable debt (complexity, coverage). Design debt, architectural debt, knowledge debt requires human judgment.
"Once we track debt, we should fix all of it." False. Fix high-impact debt. Some debt is manageable and fixing it isn't worth the cost.
"Debt tracking means we built badly." False. All codebases have debt. Tracking it shows professionalism, not failure.
Technical Debt: The debt being tracked.
Technical Debt Prioritization: Deciding which tracked debt to address.
Code Health: Technical debt is one dimension of code health. Tracking debt contributes to understanding overall health.
Code Complexity: One category of tracked technical debt.
Q: How often should technical debt be reviewed? A: Metrics should update automatically (or at least weekly). Reviews should happen monthly or quarterly. Are we moving in the right direction? Where is debt growing fastest? Quarterly deeper analysis to decide on paydown priorities.
Q: Should technical debt tracking be public? A: Yes. Dashboard visible to team and leadership. Transparency creates accountability. It also fights the narrative "we can ignore debt." Visible debt is harder to ignore.
Q: How do you know if tracked debt is important? A: Correlate with velocity. Is high complexity correlating with slow features? Is low test coverage correlating with bugs? Importance is shown through impact on team outcomes.
Keep reading
