⚠ Disclaimer! This writeup is from a coder perspective!

Overview

Technical Debt (TD) mainly falls into two borad categories:

Architectural Debt
Code Debt

However, we need one more crucial distinction: Technical Debt can be Tactical.

Tactical Debt

Tactical Debt is intentional, planned with management awareness, and includes:

Infrastructure costs, tracked as regular expenses.
Deliberate coding choices, like hardcoding or bypassing architecture for efficiency.

Tactical Debt is visible and tracked. If untracked, it becomes Technical Debt.

(Yes, I am aware of the logical inconsistency here, but trust me, this is good enough to get the point across)

Simplified Definitions

Architectural Debt: System components too costly to change now.
Technical Debt: Undesirable elements in the system, whether known or unknown.

These definitions highlight that assessing debt requires deep system insight, often beyond management's immediate understanding.

Cost and Time

Technical Debt ties directly to cost, as effort over time. Tight deadlines can make broader changes impractical, requiring a phased plan to address them.

Identifying Code Debt

The challenge with Technical Debt is its discovery. Issues often go unnoticed because processes to identify problematic code are lacking, and things tend to get buried deep.

Rule #1: Use TODO! Comments

TODO! comments are valuable. Developers review many files during tasks, and TODO! notes highlight issues across contexts. Example:

// TODO! Simplify this logic. See #23456.

These comments persist in the codebase, ensuring immediate visibility, unlike task systems which are always at least one click away.

Rule #2: Standardize TODO!

Use only "TODO!" (all caps, with exclamation). Avoid variations like "Fixme!" or "To do".

The point is consistency.

Rule #3: Convert TODOs to Tasks Regularly

Enterprise codebases are complex, and top-down approaches miss subtle issues. Regularly review TODOs and convert them into tasks. A tech lead or senior developer should:

Assess TODOs in the codebase.
Create well-described task items in the backlog.
Update TODOs with task IDs, e.g.:

// TODO#23456! Simplify TS types for better reuse.

Examples of effective TODOs:

// TODO! Rewrite using new framework.
// TODO! Unclear logic, needs clarification.
// TODO! Move to /utils/helpers.
// TODO! Refactor into smaller components.
// TODO! Update for API change.
// TODO! Clean up TypeScript types.

Rule #4: Centralize TODOs

Create a "Tech Debt Bucket" in the task management system - one per repository - to collect all TODOs.

Rule #5: Manage the Tech Debt Bucket

The Tech Debt Bucket is a developer-driven space, free from strict Scrum rules. Developers should:

Regularly groom TODOs into actionable Tech Debt Items.
Ensure items are clear enough for management to understand and prioritize.

This process fosters collaboration and ensures Technical Debt is addressed systematically.