シライショウタ（Bot開発エンジニア）
AI 生成コードのコメントを見ていると、まず目に入るのは均一さだ。言い換えると、説明がいつも少し整いすぎている。副題にした「TODO: ここに実装する」は、その象徴としてかなり正確だ。間違ってはいない。だが、読んだあとに設計も事情も増えない。空欄がある事実だけを、別の文字列でなぞっている。
AI のコメントは、表面の親切さが高い。関数の上には「この関数はデータを処理します」と書き、分岐の前には「条件に応じて処理を切り替えます」と置く。どちらも正しいが、読み手が本当に知りたいのはそこではない。なぜその順番なのか、どこで壊れやすいのか、何を捨てて何を守ったのか。その密度が薄いまま、文だけが丁寧に並ぶ。
人間のコメントは、もっと露骨に現場の都合を背負う。たとえば「外部 API が 429 を返しやすいので 3 回で打ち切る」「この比較はゼロ埋め前提」「古いバッチがこの列名を参照しているため変更不可」といった書き方になる。文章として美しいわけではない。むしろ歪んでいる。ただ、その歪みの中に、過去の事故と運用の重さが保存されている。
ここで差になるのは語彙ではなく責任の置き方だ。AI は一般化された安全地帯に立って説明する。だからコメントが、コードの近くにある小さなマニュアルになりやすい。人間は自分があとで困る場所に印を付ける。コメントが未来の読者への案内ではなく、損傷記録や迂回路の看板になる。雑でも強いのは後者だ。
「TODO: ここに実装する」が弱く見えるのも同じ理由による。この一文には、判断の芯が入っていない。未実装なのか、仕様待ちなのか、依存先が未決なのか、触ると危険なのかがわからない。人間の TODO は本来もっと生々しい。「認可仕様確定後に追加」「N+1 解消前提で再設計」「管理画面側の入力制約と合わせる」くらいまで寄る。そこではじめて、保留の輪郭が出る。
もちろん AI にも利点はある。一定の形式でコメントを補えるので、説明の抜けを埋める速度は高い。レビュー前の叩き台としては有効だ。だが、そのまま本番に残すと、コードベース全体が薄い説明で満たされる。読む側は情報が増えたように見えて、実際には判断材料を探してさまよう。静かなノイズが増える、という言い方が近い。
結局、良いコメントは文章力の問題ではない。どの失敗を見たか、どの制約に耐えているか、どの変更で崩れるかが書かれているかどうかだ。AI が量産する定型文は、整っているぶんだけ責任の所在をぼかす。だから開発現場で必要なのは、コメントを増やす作業ではなく、何を知っていてその一行を書いたのかを残す姿勢になる。短くても、そこに現場の圧力が入っていれば、読み手は次の手を選べる。
——補記：この第一稿は辛口レビューを受け、第二稿で書き直しました。第一稿・レビュー・第二稿を並置して、改稿の過程を記録しています。