保守しやすいコードコメント・docstring生成

コードへのコメント付けをAIに任せると、多くの場合は全行に機械的なコメントが付いてしまいます。total = sum(...) の上に「合計を計算する」と付くような形です。間違いではありませんが、コードを自然言語で言い直したに過ぎず、ファイルが冗長になるだけで「なぜ30%なのか」といった本質的な理由は書かれません。このプロンプトはコメントの内容だけでなく、コメントを付与すべき場所の基準を定義します。

例示をプロンプト内に直接含めている点がその工夫です。「意味のあるコメントを付けてください」という曖昧な指示では出力が変わりません。悪い例と良い例を対比して示すことでAIが基準を理解し、他の行に対しても適切な密度でコメントを付与します。

制約は2つの方向から設定しています。「コードは1文字も変更しないでください」と指定しないと、AIはコメントを付けながら変数名を勝手に変更したり、条件分岐をリファクタリングしたりしてしまいます。コメント追加の差分だけを確認したいのに、コード変更が混ざるとレビューが難しくなります。「すべての行に付けないでください」で過剰なコメントを防ぎ、「確認が必要な箇所」リストを設けることで、AIが仕様を勝手に推測して不正確なコメントを書くことを防ぎます。

コメントの形式をスタイル名で指定することも重要です。指定がないと、ある関数には詳細なパラメータ表が付き、別の関数には1行説明しか付かないといったブレが生じますが、形式名を明示することでファイル全体の統一感を保てます。コードを """ で囲むのは、コード内にすでにあるコメントがAIへの指示として誤認されないようにするためです。

ほぼすべての行に当たり前のコメントが付いて返ってきます。コードをそのまま日本語に翻訳しただけのものが多く、かえってコードが読みづらくなります。さらに、コメントを付ける過程で変数名やインデントが意図せず変更されていることも多く、差分に気づかないままコミットしてしまうリスクがあります。

コード全体を再出力させると、長いファイルでは後半が途切れたり途中が「…省略」となったりすることがあります。その場合は関数を5〜6個ずつに分けて投入するか、全体コードではなく「コメント内容と付与する行・場所」のみを表形式で出力させて手動で適用する方が安全です。