TODOs aren't for doing

Original Article ↗ Hacker News Discussion ↗

Meaning and Purpose of TODOs

  • Big disagreement over what TODO should mean:
    • One camp: TODO = actionable task that should be done eventually, ideally tracked.
    • Other camp (aligned with the article): TODO = contextual note about missing polish, edge cases, or potential improvements that may never be done.
  • Several people argue the article’s example (triple-click causes error) is a comment or “known issue”, not a real TODO.

Arguments for Inline TODOs

  • Low-friction way to record:
    • Known but acceptable limitations.
    • “Would be better if…” refactors or performance improvements.
    • Design intent and tradeoffs (“I know this is brittle; here’s how I’d improve it if I had time”).
  • Valuable for:
    • Future maintainers reading that exact code.
    • Personal projects and old/unmaintained codebases without real trackers.
    • Offloading mental load: once written, you can stop thinking about it.
  • Some see TODOs as “breadcrumbs” or “rain checks on technical debt”, not guaranteed work.

Arguments Against / TODO as Code Smell

  • Seen as:
    • Broken windows / technical debt that rarely gets paid.
    • A way to push responsibility to a hypothetical future developer.
    • Noise that must be maintained and easily becomes outdated.
  • Many teams refuse TODOs in main:
    • Either fix it, document it as a normal comment/NOTE, or create a ticket.
    • Some CI rules fail builds on bare TODO/FIXME.

Alternative Tags and Taxonomies

  • Rich vocabularies proposed:
    • FIXME = broken, must be fixed before merge.
    • XXX = ugly/obscene but working; important or risky spot.
    • NOTE / NB / WARN / HACK = unusual behavior, important context.
    • FUTURE, MAYDO, SHOULDDO, COULDDO, PERF for different priorities or types of improvement.
  • Core idea: distinguish “must-do” from “nice-to-have” and from “documentation”.

Issue Trackers vs Code Comments

  • Pro-trackers:
    • Proper triage, prioritization, visibility beyond developers.
    • Some require every TODO to link to a ticket (TODO(PROJ-123): ...).
  • Anti-/skeptical:
    • Jira and similar tools are high-friction, politicized, and slow.
    • Lightweight TODOs capture many small issues not worth full tickets.
    • Trackers often auto-close or reject low-priority “would be nice” work.

Tooling and Workflow

  • IDEs and tools:
    • TODO indexing (JetBrains, VS Code extensions, godoc notes).
    • CI hooks that reject or enforce formats (e.g., TODO + ticket link).
  • Some suggest automation that promotes lingering TODOs into tracker issues; others see this as counterproductive overhead.