TODO comments in production code: the silent technical debt accumulator

Open any large production codebase and run grep -r "TODO" .. The number is usually somewhere between “uncomfortable” and “genuinely alarming.” Hundreds of TODO comments. Dozens of FIXMEs. A handful of HACKs that someone promised themselves they’d clean up before the next release — in 2022.

TODO comments are the engineering equivalent of a Post-it note on a wall. They feel like a plan. They are actually a debt you forgot you owed, accumulating interest with every passing sprint.

Why TODO comments don’t become tickets

The intent when writing a TODO is always genuine: “I’ll come back to this.” The problem is that the TODO lives in the codebase, and the work lives in the issue tracker, and there is no automatic bridge between them. Moving a TODO into a ticket requires: noticing the TODO exists (hard once the commit is merged), deciding it’s worth tracking (subjective without context), finding the right project and priority, and writing a description. That’s 3–5 minutes of overhead per TODO — enough friction to ensure it almost never happens systematically.

The result: a growing backlog of acknowledged technical debt that exists in code comments but not in the system where engineering work gets planned and prioritised.

The compounding cost

TODO debt compounds in two ways. First, the underlying issue doesn’t improve — a workaround noted as “TODO: fix this properly” doesn’t get better over time; it often gets worse as the surrounding code evolves. Second, the codebase becomes harder to audit. When a new engineer asks “are there known issues with this module?” the answer lives in git grep output, not the issue tracker where they’d expect to find it.

What good TODO hygiene looks like

Teams with healthy TODO practices do three things differently:

• Link on commit — any TODO added to the codebase in a commit must include an issue tracker reference: TODO(#1234): fix this once we migrate off legacy auth. This makes the debt intentional and trackable.
• Automate new-TODO detection — when a commit introduces a new TODO without a linked issue, an automation creates the issue automatically. This removes the friction of the manual bridge entirely.
• Quarterly TODO audits — a scheduled review of all unlinked TODO comments in the codebase, triaged into “fix this sprint,” “add to backlog,” or “remove comment, accepted technical debt.”

Automating TODO-to-ticket with Deviera

Deviera’s github_commit_todo trigger fires when a commit is pushed that introduces a new TODO or FIXME comment. The automation creates a Normal-priority issue in your issue tracker (Linear, Jira, or ClickUp) pre-populated with the file path, line number, commit SHA, and the TODO text. The issue is linked back to the commit, making the debt visible and traceable from the moment it enters the codebase.

This doesn’t mean every TODO becomes urgent work — Normal priority means it gets triaged, not immediately acted on. But it means zero TODOs exist only in git. Every acknowledged debt item has a structured record.

The number that surprises most teams

Teams that enable TODO tracking for the first time typically see 8–15 new issues created in the first week as recent commits are scanned. After the initial burst, the steady-state rate drops to 1–3 per week — which is the actual rate at which new technical debt is being acknowledged. That’s a manageable backlog if actioned regularly. It’s an unmanageable hidden liability if not.