Guide to Cleaning Up Obsolete TODOs and Preventing Them from Distracting Your Agents

Google measured how old TODOs distract code agents. We explain how to locate them in your repository and clean them up with human review.

AI for developers

Code agents read your repository as context, and that includes forgotten comments. A Google article, reported by InfoQ, describes "agent distraction": when an agent finds an old TODO, it might try to solve something nobody asked for.

The data is striking. Approximately 13% of sessions exposed the agent to inline TODO/FIXME references, and in 6% of those cases, it acted on the referenced bug, almost always without the prompt mentioning it. These distractions led to 70% more steps, 77% more tokens, and 105% more waiting time. In this guide, we adapt the idea to any repository.

A code agent following an old TODO comment instead of the requested task — A forgotten comment can turn into an unsolicited detour.

What you need

You need read access to git history, a way to check the status of your tickets (whatever your team uses), and a PR review process. Google details that its cleaning agents sometimes had to inspect years of history to confirm that both the TODO and its intent were obsolete. Do not assume this is 100% automatable in your case.

Inventory all TODOs and FIXMEs in the repository, with file and line number.
Cross-reference each entry with its ticket status: closed, open, or non-existent.
Review the git history of doubtful cases to confirm that the intent no longer applies.
Open a PR that removes only the references confirmed as obsolete.
Request human review before merging and repeat the process periodically.

Inventorying TODOs

A simple starting point is to list occurrences with line numbers. This is just the first filter: it doesn't tell you if the ticket is still active, and you'll need to adjust the pattern to the reference format your team uses.

git grep -n -E "TODO|FIXME" -- . > todos.txt
wc -l todos.txt

Categorizing and cleaning

For each entry, decide between three destinations. If the ticket is closed, the comment is superfluous. If it's still open but out of the usual scope, it should be clearly delimited or moved to the issue tracker. If there's no ticket, ask the original author or check the history before deleting anything.

Closed ticket: delete the comment.
Open and relevant ticket: keep it, with a clear description.
No ticket or no owner: investigate the history before deciding.

According to the article, Google's cleaner removed thousands of truly obsolete references in six months, with over 95% acceptance by human reviewers. That figure is from their environment; in yours, start with small batches and measure how many proposals are rejected.

Tip Add a pre-merge check that warns when a change introduces a TODO without a ticket or one that points to an already closed ticket. Preventing new debt from entering is cheaper than cleaning it up later.

A repository with obsolete comments removed after human review — Automated cleaning, human decision.

What to expect: fewer distractions, shorter sessions, and less token usage, although the exact effect will depend on how many old TODOs your code accumulates. Another nuance pointed out by a commenter in the article itself is that the same principle can be applied to web pages with outdated or contradictory information, which also confuse AI systems.

To learn more: Chinese edition · Events · About C4Media.

Original source: infoq.com

Article generated with AI.larebelion

Guide to Cleaning Up Obsolete TODOs and Preventing Them from Distracting Your Agents

What you need

Inventorying TODOs

Categorizing and cleaning

Related articles from LaRebelión

Comentarios