シライショウタ（Bot開発エンジニア）
先月の決済連携の PR で、再試行ループの上に AI が入れたコメントは「失敗した場合は再試行します」だった。文としては正しい。だが、その下のコードが守っていたのは回数ではなく事故の種類だ。429 と 503 だけを再送し、タイムアウト時も idempotency_key を固定し、注文メモが変わっても署名対象をずらさない。そこを崩すと二重請求が出る。レビューで残したのは「503/429 のみ再送。タイムアウト後に成功していることがあるので key を変えない。注文編集時に payload を組み直すと重複決済になる」という、見た目の悪い三行だった。
差は文章のうまさではない。次に触る人間へ、どの地雷を踏むなと渡しているかだ。「再試行します」は処理の説明で終わる。読み手は安心するが、何を固定し、何を変えてはいけないかは一つも増えない。午前二時に障害通知を受けた担当が知りたいのは、関数の役目ではなく、どの変更が請求事故に直結するかだ。あれは説明ではない。隠している情報が多すぎる。
AI の TODO も同じ顔をする。実際に消したのは「TODO: バリデーションを追加」だった。その行で止めたかったのは一般的な入力検証ではない。CSV 取込の備考列が全角 81 文字で切れ、配送ラベル生成だけ UTF-8 ではなく Shift_JIS 前提で落ちる、という古い不具合の再発だ。残したコメントは「備考は全角 80 文字で丸める。ラベル印字サーバが Shift_JIS 固定のため 81 文字目で化ける。管理画面と同じ切り方に合わせる」。これなら保留の理由が読めるし、直すなら周辺も一緒に触るしかないと伝わる。
もちろん、生成されたコメントが全部不要なわけではない。公開 API の引数説明、DTO の項目要約、テストデータ生成の前提整理には十分使える。そこでは均一さが利点になる。だが、移行期のコード、外部都合で曲がった分岐、消せない互換処理に同じ調子の文を置くと、危険だけが均一に薄まる。とくにレビューで厄介なのは、何も書かれていない行より、もっともらしい一文がある行だ。読む側が理解した気分になり、確認の手数を減らしてしまう。
良いコメントは親切な要約ではなく、誤読を防ぐための偏った記録だ。 その偏りには、切り戻しで失った半日や、サポート窓口に積まれた二重請求の問い合わせ件数が染みている。薄いコメントが残ると、新しく入った開発者は善意で整理し、危険な固定値を消し、古い分岐を統合する。コードは一度きれいになる。そのあと障害が出て、履歴を掘り返した人間だけが、あの一行に欠けていたものの値段を払う。