Comments Recommended

Link every TODO to a ticket

A TODO or FIXME comment names a ticket, or it is not merged. Loose notes in the code are never planned and never found.

By Erik Bergstedt, Agent Wranglers. Updated 20 October 2026.

How to do it

Open a ticket for the work and write its ID in the comment, such as TODO(SHOP-512). If the work is not worth a ticket, delete the note. Remove the comment in the change that closes the ticket.

Example

// Bad: nobody owns it, so it stays forever
// TODO: handle refunds in other currencies
// Good: the ticket holds the plan and the owner
// TODO(SHOP-512): handle refunds in other currencies

# Bad
# TODO: handle refunds in other currencies
# Good
# TODO(SHOP-512): handle refunds in other currencies

grep -rnE '\b(TODO|FIXME)\b' src/ | grep -vE '(TODO|FIXME)\([A-Z]+-[0-9]+\)' && exit 1 || exit 0

How to check

The build fails on a TODO or FIXME without a ticket ID. Examples are Ruff TD003 for Python, or the grep below for any language.

For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers architecture playbook: https://agentwranglers.se/playbook/architecture/comments/todos-with-tickets.