L09 Todo Fixme Hack

title: "TODO, FIXME, and HACK — Managing Action Comments in Source Code" weight: 9 description: "Learn how to manage TODO, FIXME, and HACK comments effectively in source code. Master standard formats, ticket tracking integration, and cleanup processes that prevent action comments from becoming permanent technical debt." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, code-comments]

TODO, FIXME, and HACK comments track work that needs to be done, bugs that need fixing, and technical debt that needs addressing. Without proper management, these comments become permanent residents of your codebase.

In this lesson, you will learn how to manage action comments effectively.

## What You'll Learn

You will write action comments with standard formats, link them to ticket tracking, and establish cleanup processes.

## Why It Matters

Untracked action comments become noise. Developers stop noticing them. TODOs that should have been done years ago remain in the code.

## Real-World Use

DodaTech requires every TODO to reference a ticket number. CI checks for TODOs without ticket references and fails the build.

```mermaid
flowchart LR
  A[Action Comment] --> B{Has Ticket?}
  B -->|Yes| C[Tracked]
  B -->|No| D[Blocked]
  C --> E[Can Be Prioritized]
  D --> F[May Become Permanent]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Standard Formats

Use TODO for planned enhancements or features that should be added. Always include a ticket reference.

Use FIXME for known bugs that need fixing. FIXME without a ticket creates untracked bugs.

Use HACK for temporary workarounds that should be replaced with proper solutions. Document why the hack exists and when it can be removed.

Use XXX for particularly urgent or dangerous code that needs attention.

# TODO: Add support for parallel compression
# TODO-456: Implement multi-threaded compression for large files

# FIXME: Memory leak in streaming decompression
# FIXME-789: Fix memory not released when decompression is cancelled

# HACK: Workaround for bzip2 bug in version 1.0.8
# Remove this when we upgrade to bzip2 1.1+
# The bug causes incorrect block sizes for files over 4 GB.

Ticket Integration

Every action comment should include a ticket number from your issue tracker. This ties the comment to a tracked item.

When a ticket is resolved, remove the corresponding comment. Do not leave resolved TODOs in the code.

Use ticket references in the format PROJECT-123 so they are searchable and linkable.

# CI check for TODO without ticket reference
# This script flags TODOs that lack a ticket number.

import re
import sys

def check_todos(file_path: str) -> list[str]:
    """Check for TODOs without ticket references."""
    issues = []
    with open(file_path) as f:
        for i, line in enumerate(f, 1):
            if "TODO" in line and not re.search(r"[A-Z]+-\d+", line):
                issues.append(f"{file_path}:{i}: TODO without ticket reference")
    return issues

Common Mistakes

1. TODOs Without Tickets

Action comments that are not tracked. They become permanent noise.

2. No Date on TODOs

TODOs without dates. You cannot tell how old the TODO is or whether it is still relevant.

3. Resolved TODOs Not Removed

Comments for work that was already done. Leftover TODOs confuse readers.

4. HACKs Without Replacement Plan

Temporary workarounds without documentation of the proper solution.

5. Action Comments as Documentation

Using TODO instead of proper documentation. TODOs track work, not describe behavior.

6. Too Vague

TODO: Improve this without saying what improvement is needed or why.

7. No Ownership

Action comments without an owner. No one knows who is responsible.

Practice Questions

1. What is the difference between TODO and FIXME?

TODO tracks planned enhancements. FIXME tracks known bugs.

2. Why should every TODO reference a ticket number?

Tickets make TODOs trackable. Without tickets, TODOs become permanent noise.

3. When should a HACK comment be used?

For temporary workarounds that should be replaced. Document why the hack exists.

4. What should happen when a TODO's ticket is resolved?

Remove the comment. Resolved work should not leave reminders in the code.

5. Challenge: Audit a codebase for action comments. Count the number of TODOs, FIXMEs, and HACKs. Check which have ticket references. Write a report with recommendations for cleanup.

FAQ

Mini Project

Set up a CI check that scans for TODO and FIXME comments without ticket references. Create a script that lists all action comments in the codebase with line numbers. Run it on an existing project and fix all TODOs without tickets.

What's Next

Next: Documentation Tools