【ITニュース解説】Stop putting TODO comments in sample code

システムエンジニアを目指す皆さんがプログラミングを学ぶ上で、チュートリアルやドキュメントから提供されるサンプルコードを利用する機会は多いだろう。しかし、そのサンプルコードをコピーして自分の開発環境に貼り付けた途端にエラーが発生し、何が問題なのか分からず困惑した経験はないだろうか。この記事は、そのようなフラストレーションの原因となっている、サンプルコードにおける特定の記述方法の問題点を指摘し、より良い改善策を提案している。

具体的には、サンプルコードの中に「# TODO(developer): ここにインスタンスIDを設定してください」といった形式のコメントが記述され、その下の行がコメントアウトされているようなパターンが問題視されている。これは「コピー＆ペーストで完了できるパターン」と呼ばれ、開発者がサンプルコードをそのまま利用する前に、手動でコメントアウトされた行を解除し、適切な値を入力することを求めている。しかし、この方法は開発者に余計な手間をかけさせ、学習の初期段階でつまずく原因となる。このような手動での修正を強いる習慣は、今日では変えるべきだという主張である。

理想的なサンプルコードとは、開発者がコピー＆ペーストした後にすぐに動作するものである。具体的には、必要な設定値が関数の引数として明示的に宣言された「コピー＆ペーストで呼び出し可能な関数」の形式か、あるいは安全なデフォルト値や環境変数を利用して、単独で実行できる「コピー＆ペーストで実行可能なスクリプト」の形式が望ましいとされる。最近ではAIアシスタントや自動化ツールがアプリケーション開発に広く利用されており、これらのツールがTODOコメントを含むサンプルコードを処理すると、そのままコメントを再現したり、存在しない値を生成したりする可能性があり、結果として人間が不完全なコードをデバッグする手間が増えるという新たな問題も発生している。

なぜ、サンプルコードの作成者はTODOコメントを使いがちなのだろうか。その背景には、コードの作成者が自身のプロダクトについて深い知識を持っていることが挙げられる。プロダクトのセットアップ手順や必要なリソース識別子など、内部のコンテキストが当然のこととして理解されているため、「TODOコメントを書けば、残りの手順は読者が自明に理解するだろう」と考えてしまう傾向があるのだ。しかし、このTODOコメントは、実際には読者にその理解の負担を丸投げしているに過ぎない。サンプルコードの作成段階でTODOコメントを禁止することで、作成者は「このコードはどのように実行されるべきか」「どのような値を安全なデフォルトとして提供できるか」「どのような前提条件を事前に明記すべきか」といった本質的な問いに、初期段階から向き合わざるを得なくなる。

具体的にTODOコメントが使われがちな状況は主に三つある。一つ目は、APIの利用例のような関数内で完結するコード片の場合で、環境によって異なる値や事前設定が必要な場合にTODOが使われる。これは、環境に関する入力をビジネスロジックから分離し、明示的な関数パラメータとして定義すべきだ。二つ目は、PythonやJavaScriptのスクリプトのように、プログラム全体で実行されるコードの場合で、引数を受け取る関数が存在しないためにTODOが使われる。この場合は、環境変数や安全なフォールバックを持つトップレベルの変数初期化が適切である。三つ目は、設定ファイルやデータベースのクエリ、Terraformのような宣言的なファイルで、特定の値を指定したいが、引数や環境変数が使えない場合にTODOが使われる。この場合は、予測可能な例示用のリテラル値や、実際に存在する公開された読み取り専用のリソースへの直接参照を提供するべきだ。

このTODOコメントを多用する習慣は、開発者体験に大きなコストをもたらす。まず、コピー＆ペースト後に手動修正が必要なコードは、最初のステップで開発者の信頼を損なう。動かないコードは開発者の学習意欲を削ぎ、心理的な障壁を生み出す。開発者はまずコードが動く成功体験を得てから、詳細な設定に取り組むべきである。次に、TODOコメントは関数の本当のパラメータ契約を曖昧にする。関数のシグネチャ（引数の定義）は、その関数が何を必要とするかを明確に示す契約だが、TODOコメントが関数本体内にローカル変数の形で登場し、引数を無視させるような記述になっていると、本来渡されたはずの引数が使われず、意図しない挙動を引き起こす「変数シャドウイング」といったバグにつながる可能性がある。

さらに深刻なのは、AIエージェントの利用が増える現代において、TODOコメントが引き起こす問題である。多くの開発者がAIアシスタントにコードの生成や統合を依頼しているが、過去のコードベースにTODOコメントが溢れていたため、AIモデルもこのパターンを学習してしまっている。そのため、AIが生成するコードにも、変数宣言がコメントアウトされたままの不完全なコードが含まれることが頻繁にあり、開発者はその不備を自力で修正しなければならない。最悪の場合、AIエージェントが自動的にコードを実行しようとして、不足している変数のために失敗し、そのプラットフォームの利用を諦めてしまう可能性すらある。AIエージェントがコードを直接実行する機会が増えている現代では、サンプルコードはデフォルトで安全であるべきだ。「example-bucket」のような接頭辞を使用することで、たとえAIが誤って本番環境でコードを実行しても、安全に失敗するか、無害な一時リソースを作成するにとどまり、重要なデータを改変するリスクを避けられる。

自動化ツール、特に継続的インテグレーション（CI）やリンターにも悪影響がある。コメントアウトされたコードをCIでテストするのは非常に難しい。ビルドシステムが動的な言語（Python、Rubyなど）では、テスト時に変数をコードに注入するような複雑な仕組みで対応できる場合もあるが、Go、Java、C#のようなコンパイル言語や厳密なスコープを持つ環境では、そのような動的な注入は不可能だ。結果として、CIパイプラインで正規表現を使ってコメントを解除するような、手間のかかる前処理を維持する羽目になる。また、一般的なソフトウェア開発において、TODOコメントは「作業が未完了である」ことを示すため、リンターではエラーとして扱われるのが普通だ。しかし、ドキュメントに意図的なTODOコメントがあると、リンターは未完成のドラフトと説明用のプレースホルダーを区別できなくなり、本来の品質チェック機能が損なわれてしまう。TODOコメントを完全に排除すれば、リンターのような静的解析ツールは再び明確な品質ゲートとして機能し、CIも標準的な単体テストフレームワークでコードをテストできるようになる。

では、この悪しき習慣から脱却し、より良いサンプルコードを作成するにはどうすればよいのか。まず、グローバルなスクリプトとしてコメントアウトされた変数を記述する代わりに、ロジックを関数としてラップし、標準的なプログラミングパターンに従って入力（引数）を定義することが推奨される。例えば、プロジェクトIDやロケーションといった必要な情報を、関数の引数として明示的に宣言し、オプションで安全なデフォルト値も設定する。これにより、コードは「コピー＆ペーストで呼び出し可能」となる。

次に、もしサンプルコードがスタンドアロンのスクリプトとして実行される必要がある場合は、環境変数を利用し、同時に安全なフォールバック（デフォルト値）を設定するべきだ。例えば、OSの環境変数からプロジェクトIDを取得し、もし設定されていなければ「example-project-id」のような警告付きのデフォルト値を使用する。このように標準的な構成要素を利用することで、たとえ開発者が初めてそれらに触れるとしても、理解しやすい普遍的なパターンを提供できる。これは、プラットフォーム固有の複雑な設定手順を推測させるよりも、はるかに優れたアプローチである。

さらに、前提となるリソースのプロビジョニング方法をユーザーに推測させるのではなく、可能な限り公開された読み取り専用のフィクスチャ（例えば、誰でもアクセスできるデータベーステーブルや公開ストレージバケット）をデフォルトのターゲットとして提供することが重要である。これにより、開発者は「Hello World」のような基本的な動作確認をすぐに成功させることができ、インフラの準備といった回り道をすることなく、学習の流れに集中し続けることができる。

そして、これらの新しい設計基準を確実に実行するためには、自動化されたツールの導入が不可欠である。サンプルコードを格納するフォルダ内でTODOコメントを含むコミットを拒否するような自動チェックを設定することで、スタイルガイドラインを客観的かつ強制力のあるルールにできる。

まとめると、サンプルコードにTODOコメントを記述することは、一時的には手軽なショートカットのように思えるかもしれないが、開発者体験やAIツールが引き起こす長期的なコストは計り知れない。私たちは、クリーンで、テスト可能で、すぐに実行できるコードを書くことにコミットし、業界全体でサンプルコードのアーキテクチャについてオープンに議論すべきである。プロダクションコードと同じくらい真剣にサンプルコードの品質に取り組むことで、開発者全員が恩恵を受けることになるだろう。