ハクソク

世界を動かす技術を、日本語で。

TODOは実行するためのものではない

307日前原文(sophiebits.com)

概要

TODOコメント は単なる作業リストではなく、 知識や意図の共有 にも役立つ。 全てをバグトラッカーに記録したり、 古いTODOを自動削除 する運用は推奨されない。 優先度の低いTODO でも、コードの背景や未対応のケースを示す価値がある。 TODOは将来の読者にとって 有用なヒント となる場合が多い。 適切なTODOコメントは チームの知見 を蓄積する役割を果たす。

TODOコメントの運用に関する誤解

  • 全てのTODO をバグトラッカーに登録する運用の非推奨
    • バグ管理ツールへの過度な登録による 運用コスト増大
  • 古いTODO を自動削除する運用の問題点
    • 時間経過のみで 価値ある知見 が失われるリスク

TODOコメントの本質的な価値

  • TODOコメントは 必ずしも実施計画 である必要なし
  • 例: 明確な未完了作業 （来週のリリースまでに対応必須な部分）なら、追跡管理が妥当
  • しかし多くは エッジケースや改善案 の記録
    • 例: 「ユーザーがボタンを三回連続クリックした場合にエラーとなる」などの レアケースの指摘
  • 優先度が低くても、コードの文脈や設計意図を伝える手段

TODOコメントの具体的な効用

  • コードの背景情報 や「なぜ現状の実装なのか」という 設計判断の記録
  • 将来の読者が 疑問を持った際の手がかり として機能
  • 「本当にこのままで良いのか？」という 再設計のきっかけ を与える
  • 作者の思考や検討事項 を残すことで、チーム全体の知見共有を促進

適切なTODOコメントの運用指針

  • 即時対応が必要なTODO のみをバグトラッカーで管理
  • その他のTODOは コード内に残し、文脈や意図を明記
  • 自動削除ではなく、定期的なレビュー による整理がおすすめ
  • TODOコメントの内容が 将来的な参考や議論の材料 となることを重視

まとめ

  • TODOコメントは 単なる作業指示 ではなく、 知識の記録 としての役割が重要
  • 適切な運用と整理 により、コードベースの価値向上を実現

Hackerたちの意見

同意だね。追跡する価値がない既知の問題のためのスペースが必要だと思う。実際には理解しておくべき問題だけど、修正するのが難しいかもしれないもの。時間があるときに、何か整理できることがないかCtrl-Fで探せるような感じ。TODOを単なるコードの匂いとして扱うツールやプロセスが多いのには本当にイライラするよ。

└

まだそういう問題に出くわしたことがないな。優先度は低いかもしれないけど、壊れた窓（『Pragmatic Programmer』の本）みたいなもんだよね。直さないタイプの問題なら、ソフトウェアのドキュメントに追加しとけばいいんじゃない？

これを聞くと、「完璧は善の敵」という言葉を思い出す。理想的には、こういう技術的負債やコードの匂いはもっと良くキャッチ・トラック・説明されるべきだけど、実際にはコンテキストスイッチやJIRAチケットを記入するような高負荷な作業に関わることになるから、追跡自体が discourages されちゃうんだよね。少なくともインラインのTODOはどこかに記録されてるし、実行するためのものでもあるから。

└

Gitのコミットメッセージに入れちゃえばいいよ。ほとんどのコミットはあんまり良くないし。TODOで石器時代に戻るのではなく、もっと良いツールの使い方を促進したらどう？多くの人はあまり頻繁にコミットしないし、無関係な変更を絡めちゃうことが多い。最後に、コミットメッセージが「somefile.pyを更新しました」とか、似たような役に立たないものだったら最悪だよね。

└

大きなコードベースだと、いろんな人からのTODOがたくさんあって扱いにくくなるのは分かるけど、個人プロジェクトではいつも良い妥協だと思ってる。私にとっては、「うん、もっと良くできるのは分かってるけど、これで思考の流れを壊したくない」ってことなんだ。機能を壊すほどの重要性はないし、ただちょっと良くなればいいって感じ。たまに思いつきで何かに戻って、サクッと修正したいときにTODOのハイライトがエディタで役立つのは本当にありがたい。（でも、実際にはそんなに頻繁にあるわけじゃないし、大抵は無期限に放置されるけどね）

└

JIRA用のMCPサーバーがあって、AIがチケットを自動で記入してくれるんだよね、Cursorの中からそのまま。

└

重要なのは、時々コードに作業が必要だっていうサインが欲しいってことだよね。そういう場合、JIRAやGHのイシューで追跡しても、やっぱりリンクは必要だと思う。参照は継続性への賭けみたいなもので、コメントに説明がないと、いつかその意味を失っちゃうかもしれない。

記事の例: > // TODO: ユーザーがこのボタンをトリプルクリックすると、クリックハンドラーがエラーになる。これは私には実際のTODOというよりコメントに見える。こういうコメントは役に立つと思うけど、TODOにはならないよね。TODOは特定のタイプのコメントを意味する。タスクを示すもので、実際にやるべきことを指し示すもの（例えば、TODO: この関数はXYZで別の値を返すべき）。だから、それはトラッカーに記録するのが適切で、コードの中に埋もれさせるべきじゃない。例の中ではバグを文書化してるだけで、実際のアクションはない。私の経験上、TODOはPRでクイックで雑なコードを承認させるための手段になってることが多い。大抵は実行されず、未来の開発者に「もっと時間があるだろう」と責任を押し付けるだけなんだよね（つまり、実際には起こらない可能性が高い）。

└

コメントは通常、コードが何をしているのかを説明するためのものだよね。例えば「// ユーザーがこのボタンを3回クリックすると、クリックハンドラーがエラーになる [xyz]」って書いても、パッと見でこの挙動が望ましくないってのは分かりにくい。これはバグなのか、それともこういうもんなのか？「TODO」は、個人的には「ここは理想的じゃないから、コードに取り組むときは覚えておいた方がいいかも」っていう簡単なマーカーだと思ってる。もし君やレビュー担当者が、修正が実装されないのはダメだって分かってるなら、もちろん、ちゃんと実行される場所で追跡しておくべきだよ。私の経験では、TODOコメントを避けると、ドキュメントが少なくなって、コードが良くなるわけじゃないんだよね。

└

それはスキップだね。ほとんどは、やらなくても大丈夫。問題なのは、コードが完全に機能してないのに、そうだと思い込んでること。私のお気に入りのTODOは、クラスEncryptedSharedPreferencesに「TODO: これを暗号化する」っていうのがあった。私が入る前に書かれたもので（絶対に承認しなかっただろうけど笑）、このコードが実際に暗号化されてないってことが明確になってたから、他のモジュールで暗号化されてるかどうかを考えたり、二重に暗号化しちゃう心配をしなくて済んだ。

└

それは「良い」TODOコメントの例としては好きじゃないな。だって、そのコメントを書くのと同じ労力で問題を直せるか、少なくともエラーじゃない何かをさせることができるから（その後、「トリプルクリックは無視されます [xyz]」みたいなコメントを残すとか）。トリガーとエラーの理由を特定するためにすでに努力してるわけだから、たぶん80%はできてると思うよ。

私は以下のように追加してgrepしてるよ: - FIXME: これは明らかに壊れてる/間違ってる、最優先 - XXX: これは「見た目が悪い」か間違ったことを前提にしてる、次に優先度が高いかも - TODO: いつか、全く違うアプローチ/カテゴリ/ブランチを実装する - NOTE: ランダムなコメントよりも重要なコードコメント NOTE: 私は古い/メンテされていないコードベースでよく作業するから、「コードが真実」って考えで、「JIRAチケット作成」ではなく、読みながら修正する感じ。

└

これ、私もほぼ同じことやってる。XXXは「ここ見て！これ大事だよ！」とか「これ、予想外かも！」って意味だね。NOTEはあんまり使わないけど、たまに使うこともあるよ。

└

理論上は素晴らしいけど、ツールなしではこれらの規約は意味がないと思う。チームで作業している前提だけどね。とはいえ、意味がないわけじゃない - もしかしたらこれに対するツールがあるべきかもしれない。

└

私にとって、XXXは「次のプルリクエストの前にこれを直せ」っていうメモみたいなもんだよ。真面目にやる気なら、この文字列を含むコメントがあるコードはCIで拒否するように設定するよ。だから、その意味では一番優先度が高いんだ。

└

私はこんな感じで使ってるよ：- TODO: リリース前に必要、必須じゃないと別のカテゴリに。リリースをブロックする。- FUTURE: 最終的にTODOになる予定、オプショナル、しばしばアーキテクチャ的なもの - MAYDO: あったらいいな、かなりオプショナル - PERF: パフォーマンスがもっと必要な場合にやる + ドメインに関連するセマンティックタグ 意見としては、TODOはコードの匂いじゃない、むしろコードベースの最も価値のある部分に集まるものだと思う。

└

私も似たようなことをしてるよ。未完成で避けられるコードパスには、FIXMEの代わりにアサーションを置いてる。私のTODOは、パフォーマンスや明確さのためのリファクタリングを含む可能性のあるタスクに関連してる。私のNOTEは、歴史的な情報を追跡するためや、その時の考えをキャッチするために使ってる。コードを見ただけではすぐには分からないことね。

└

これをやろうと思ってたことが多かったけど、いつもためらってたのは、他にやってる人がいないからだった。今、他の人がTODO以外のラベルを使ってるのを見て、俺もこれを始めるかもしれない。

└

このスタイル好きだな。俺が関わったプロジェクトでは、CIがFIXMEは完全に拒否して、問題チケットがないTODOもダメだった[^1]。階層はこうだった：FIXME: 自分が気を散らさないようにメモを残してるけど、このコードは解決されるまで完成/マージ可能とは見なされない。XXX: これ、早めに直す必要があるけど、コードはそれなしでも機能する。TODO: これ、再検討が必要だけど、コードは問題なく使える - 優先度は低い。XXX NOTE: これ、ちょっと変わったことをするから、このコードに取り組むときは気をつけてね。[^1]: これをする（またはしない）価値については、すでに他のコメントで散々議論されてるよ。

「TODOは常に具体的な問題を指し示すべき」という立場から言うと、マージする前にTODOを解決する方法は3つあるよ: 1. 問題をファイルする。実際にやるべきことなら、20秒で書き留めて追跡すればいい。 2. そのままやっちゃう。問題をファイルするほどの小さなことなら、コミットする前に直しちゃえばいい。 3. コメントにする。修正する価値がなくて追跡する価値もないけど、覚えておきたいなら、普通のコードコメントとしてそれでいい。ブロッコリーを食べよう。TODOを追跡しよう。

└

トラッキングが20秒で済むといいな。私の組織（大手テック）では、JIRAのチケットに10個以上の必須項目があるんだ。

└

そうそう！PRをマージする前にTODOが消えてるかCIチェックを追加することが多いよ。自分のブランチにはいくらでもTODOがあってもいいけど、マージする前に上の3つのうちのどれかをやってね（時にはどんなTODOでも、時にはTODO_P0）。CI統合があるとTODOがもっと役立つと思う。作業中のブランチで本当にやるべきTODOを追跡できるし、CIがそれを見逃さないようにしてくれるからね。

└

20秒かけて書き留めてトラッキングする あなたはTODOを説明してるね。もしこれをチケットシステムに昇格させるとしたら、明らかに20秒以上かかるし、助けにはならず、むしろ気が散るだけだよ。

└

著者は基本的に#3を主張してるけど、TODOコメントと非TODOコメントの違いには触れてないと思う。TODOって言葉には視覚的な魅力があって、すぐにコメントのクラスを理解できるんだよね。それが私がTODOコメントを普通のコメントにするよりも維持したい理由かな。でも、著者がTODOコメントは何かをやる必要があるわけじゃないって主張してるのを見ると、ちょっと臭いよね。記事の意見には大体同意するけど、あなたの選択肢#3の非TODOコメントにするのは改善だと思うよ。

└

重要なポイントは、コードにTODOコメントを入れたら、マージする前に解決すべきだってことだよ。そこに残すほど重要なら、イシューにすべきだと思う。私は、grepで探すためだけに使ってるし、「あ、これ直さなきゃだけど、今は別のことやってるからTODOを書いて、今やってることを終わらせてからTODOに戻る」って感じで使ってる。

└

外部システムでの追跡は、イシューをファイリングするだけじゃなく、トリアージやバックログ管理、まだ問題かどうかを再トリアージすること、そして完了したらクローズすることにもオーバーヘッドがかかるんだ。外部システムのイシューは、この特定のコードに取り組んでいる開発者に見落とされることもある。修正する価値のある小さなことはたくさんあるけど、それを追跡するオーバーヘッドには見合わないことも多い。コード内のTODOは、誰かがこのコードに取り組んでいるときに簡単に見つけられるし、コードがリファクタリングされたときに簡単に削除できる。

これはスタイルの問題だね。人によってTODOの定義や文化は違うから。俺のコードベースでは、ここで説明されている通りにTODOを使ってる。TODOは実際には実装を文書化するためのコメントで、特に何かが欠けていて役に立つかもしれないことを記録してるだけ。実際にやらなきゃいけないってわけじゃないと思う。コードベースの中でコメントを実際のタスクリストとして使うのは意味がないと思う。優先順位は常に変わるし、コードを書いたときには重要だと思ったことが、実際にはそうじゃなかったり、書いてるときに考えなかったことが必要になったりするから。TODOコメントを現在の考えを反映するために常にPR出して更新してるの？まあ、そうすることもできるけど、バグトラッカーや更新が楽なテキストドキュメントでそのリストを管理する方が理にかなってると思う。

完全に反対だね。バグを報告するつもりがないなら、TODOを書くなよ。// TODO: ユーザーがこのボタンを三回クリックすると、クリックハンドラーがエラーになるから[xyz] これは現在の状況を文書化してるだけで、TODOじゃないし、その言葉はコメントに入れるべきじゃない。

面白いね。昨日、あるライブラリのソースコードを見てたら、TODOがたくさん散らばってるのに気づいた。最初は、これは赤信号だと思って、このライブラリは使わない方がいいかもって思った。でも、全部読んでみたら、非常に稀なエッジケースや、ちょっとした最適化、将来の最適化に関するメモだった。すぐにこのスタイルのTODOを採用したよ。

タイトルはちょっとクリックベイトっぽいけど、その気持ちには完全に同意する。さっき、#TODOが極めて稀なエッジケースを扱うことを示してたけど、そこに入れてから2年間一度も見たことがなかった。それでも、コードを振り返ったときに、なぜそれが処理されていなかったのかを考えると、他の人や未来の自分には役に立つだろうね。時々、これらはただのコメントでいいと思う。環境によるけど、俺は2人のチームで自分のコードベースを維持してるから、こういう風にTODOを使うことにしてる（時々ね）。

└

俺がいたチームでは、これを目的に// TBD: [...]を使ってたから、「TODOの人たち」に気づかれないようにしてた。

TODO.aiを紹介するよ。君のTODOを全部管理するから。