開発中に「あとで直す」「一時対応」「本当は整理したい」と思う場面はよくあります。そのときに便利なのがTODOコメントです。コードの近くに残せるため、作業中の判断や未対応の論点を忘れにくくなります。
ただし、TODOコメントは残した瞬間よりも、その後の扱いが重要です。担当者も期限も理由もないTODOは、時間がたつほど意味が薄れます。気づけば誰も触れないコメントになり、保守時に「これはまだ必要なのか」と毎回迷う原因になります。
この記事では、TODOコメントを完全に禁止するのではなく、放置されにくい形で残し、チームで回収するための運用ルールを整理します。
TODOコメントは悪ではないが、放置されると負債になる
TODOコメント自体は悪いものではありません。開発中には、すぐに直せない問題や、別チケットで対応したい課題が出てきます。すべてをその場で解決しようとすると、作業範囲が広がりすぎることもあります。
問題は、TODOが「次に何をすればよいかわからないメモ」として残ることです。
たとえば、次のようなコメントは後から判断しづらくなります。
// TODO: あとで修正するこのコメントだけでは、何を修正するのか、なぜ今は直さないのか、誰がいつ見るのかがわかりません。数週間後に見た人は、消してよいのか、残すべきなのか、別の不具合につながるのかを判断できません。
TODOコメントは、未来の開発者に向けた連絡です。未来の開発者には、今の作業背景が見えていません。そのため、残すなら「判断できる情報」まで一緒に残す必要があります。
放置されないTODOコメントに必要な情報
放置されにくいTODOコメントには、共通して必要な情報があります。最低限、理由、次の対応、参照先、期限または見直しタイミングを残します。
書くべき情報
良いTODOコメントは、読んだ人が次の行動を決められる形になっています。
// TODO: 旧APIの廃止後に新APIへ切り替える
// 理由: 取引先の移行完了までは旧APIレスポンス形式を維持する必要がある
// 対応: ticket-1234 の完了後に removeLegacyResponse() を削除するこの形なら、なぜ残っているのか、どの作業と関係しているのか、何が終われば削除できるのかがわかります。コメントを見た人は、チケットを確認して次の判断に進めます。
TODOコメントに入れたい情報は、次の4つです。
- なぜ今すぐ対応しないのか
- 次に何をするのか
- 関連するチケットや資料はどこか
- いつ、またはどの条件で見直すのか
すべてを長く書く必要はありません。大事なのは、未来の判断に必要な情報を残すことです。
書かないほうがよい情報
一方で、TODOコメントに作業中の感想や曖昧な愚痴を残すのは避けます。
// TODO: ここ微妙
// TODO: なんか重い
// TODO: そのうち整理こうしたコメントは、問題の存在を示してはいますが、次の行動につながりません。特に「そのうち」「あとで」「微妙」のような言葉は、時間がたつとほとんど意味を失います。
また、仕様判断や顧客との合意内容をコードコメントだけに閉じ込めるのも危険です。重要な背景は、チケット、設計メモ、議事録など、チームが参照しやすい場所にも残します。コードコメントは、その参照先へつなぐ入口として使うほうが安全です。
チケット・期限・レビューとつなげる
TODOコメントを放置しないためには、コード内だけで完結させないことが重要です。コメントを書いたら、チケットやレビューとつなげます。
まず、TODOコメントにはチケット番号を付けます。チケットがないTODOは、誰の作業にも紐づきません。もしチケットを作るほどでもないなら、本当にTODOとして残す必要があるのかを見直します。
次に、期限または見直し条件を決めます。日付で区切る場合もあれば、「次回リリース後」「外部API移行完了後」「検証環境の確認後」のように条件で区切る場合もあります。期限がないTODOは、優先度が下がり続けます。
コードレビューでは、TODOコメントを見つけたら次の観点で確認します。
- 関連チケットがあるか
- 今すぐ対応しない理由が書かれているか
- 削除または修正する条件が明確か
- 本番障害につながる重要な問題を先送りしていないか
- コメントだけでなく、チケット側にも背景が残っているか
このレビュー観点があるだけで、TODOコメントはかなり残しにくくなります。残してはいけないという意味ではありません。残すなら、回収できる状態にするというルールです。
既存TODOを棚卸しする手順
すでにTODOコメントが多いプロジェクトでは、いきなり全削除しようとしないほうが安全です。古いTODOの中には、過去の障害対応、顧客都合、外部サービスの制約が含まれていることがあります。
まず、コード検索でTODOコメントを一覧化します。次に、内容を次の3つに分けます。
| 分類 | 判断 | 対応 |
|---|---|---|
| すぐ消せる | すでに対応済み、または意味がない | 削除する |
| チケット化する | 対応が必要だが今すぐではない | チケットを作り、コメントに番号を付ける |
| 調査する | 背景が不明で判断できない | 担当者、履歴、ログ、過去資料を確認する |
棚卸しでは、古いコメントを「残すか消すか」だけで判断しないことが大切です。背景が不明なものは、まず調査対象にします。無理に削除すると、過去に避けていた問題を再発させることがあります。
チームで運用するなら、月に1回、またはリリース前にTODOコメントを確認する時間を決めると効果的です。新しいTODOを増やさないだけでなく、既存のTODOを減らす習慣を作れます。
まとめ
TODOコメントは、開発中の判断を残すために便利です。ただし、理由や期限、参照先がないまま残すと、時間がたつほど判断しづらい負債になります。
放置を防ぐには、TODOコメントを作業メモではなく、チームで回収する管理対象として扱うことが大切です。関連チケット、残す理由、次の対応、削除条件をセットにすると、未来の開発者が迷いにくくなります。
まずは既存のTODOコメントを一覧化し、「削除する」「チケット化する」「調査する」に分けるところから始めると、無理なく運用に乗せられます。
