【コード哲学エッセイ】 TODO コメントを借金のまま放置しない
未来の自分と握手するメモの残し方
「ここはリファクタしたい」
「エラーハンドリングを足す」
「コメントを整理する」
そんな TODO が、気づけば数百行のコードに散らばっている。
動いているから大丈夫、と自分に言い聞かせて、そのまま次の機能開発に移っていく。
かつての僕は、そうやって借金を積み上げていました。
半年後、 自分が書いた TODO の意味が分からなかった
サラリーマン時代の医療系システム開発で、納期に追われて「後で直す」と TODO を残したままリリースしたことが何度かありました。
決算に合わせた納品、障害対応、次の年度の仕様詰め。
「動いているから大丈夫」と自分に言い聞かせて、そのまま次の機能開発に移っていました。
半年後、障害対応でそのコードを開いたとき、胸が冷たくなりました。
「この TODO、何を指してたんだっけ？」
自分が書いたはずのコメントが、まるで他人の字のように読めない。
当時の文脈も、なぜこの実装にしたのかも、すっかり忘れていた。
結局、全体を読み直す羽目になり、深夜までサーバールームにこもりながら調査に費やしたあの夜を、僕は忘れられません。
借金を放置したツケが、未来の自分に回ってきた。
そう感じた瞬間でした。
「後で」 だけの TODO は、 ほぼ確実に借金になる
フリーランスになってから、僕は TODO の扱いを少しずつ変えました。
「後で」だけ書いておく TODO は、ほぼ確実に借金になる。
だから、期限か Issue のどちらかは必ず付けるようにしています。
// TODO(2026-03): エラーハンドリングを追加。現状は上位で握っているが、ここでも検証したい
// TODO: #123 で対応予定。リファクタ時にこの分岐を整理するたったそれだけのルールで、「いつかやる」が「今週やる」か「Issue に昇格する」かに変わりました。
週次の振り返りで TODO を一覧し、「消化するか、Issue に移すか、それとも削除するか」を決める習慣も、借金をため込まないための境界線になっています。
「なぜ」 を一言、 添えておく
もうひとつ、僕が心がけているのは、「なぜこの実装にしたか」を短く書いておくことです。
// 〇〇のため、△△ではなく□□を採用。2026-03 時点の判断理由と日付を入れておくと、半年後に見返しても「あのときはこう考えていた」と再現できて、未来の自分が助かります。
逆に、「要リファクタ」「要改善」だけ書いて、何をどう直すか書いていなかったときは、未来の自分には文脈が伝わらず、結局また調査からやり直すことになりました。
「何を」「なぜ」「いつまでに」のうち、少なくとも 2 つは書いておく。
そのささやかな一手間が、未来の自分との握手になるのだと、僕は思っています。
TODO は借金ではなく、 未来へのメモ
TODO は借金ではなく、未来の自分へのメモとして扱いたい。
放置せず、期限や Issue で追える形にしておく。
「なぜこう書いたか」を一言添えておく。
その積み重ねが、未来の自分がコードを開いたときに、「ああ、あのときの僕はこう考えていたんだな」と安心して読み進められる、ささやかな架け橋になる。
今日書く TODO が、半年後のあなたを助けるか、苦しめるか。
未来のあなたを救えるのは、今のあなただけです。
ひとりごと
TODO コメントを借金のまま放置していた頃の僕は、未来の自分に判断を丸投げしていました。
「後で直す」と書いて、そのまま忘れる。
半年後に開いたコードが、自分でも読めない暗号になっていたあの夜以来、僕は TODO に期限か Issue を付け、「なぜ」を一言添えるようにしています。
このエッセイを読んでくれたあなたも、もしコードに TODO を残すとき、未来の自分が「ありがとう」と言ってくれるような、ささやかなメモを添えてみてください。
その一手間が、未来の自分との握手になります。
あわせて読みたい
▼ コメントに意図を残したいときに
コードが語る「結果」と、コメントが語る「意図」を分ける。
TODO に「なぜ」を添えるのと同じように、未来の読者に届くコメントの書き方を綴ったエッセイです。
次の一歩を一緒に決める 「作戦会議室」 へ
TODO を借金にしないというのは、コードを書く姿勢の話でもあります。
作戦会議室では、リファクタリングの進め方や、週次レビューで技術的負債と向き合う習慣についても、仲間と一緒に言語化していく場があります。
一人で抱え込まず、少しだけ誰かと話してみる。
その一歩として、作戦会議室の扉を開いてみてください。
