プルリクエストの説明とコードコメント、その明確な使い分け：より良い開発のために

プルリクエストの説明文 — レビューを「説得」する情報

プルリクエストの説明文は、あなたの変更がなぜ受け入れられるべきかを正当化する場です。PRのタイトルでは、修正している問題や追加する機能を具体的に記述する必要があります。例えば、「ウィジェットの極性反転をサポートする」や「極性変化時のウィジェットのクラッシュを修正する」といった形です。

大規模なコードベースでは、タイトルはさらに詳細であるべきだと述べられています。例えば、単に「極性反転のサポートを追加」ではなく、「ウィジェットの極性反転をサポートする」のように具体性を高めることで、将来のデバッグ作業で関連する変更を素早く特定しやすくなります。

PRの説明は、その時点での情報であり、コードレビューそのものに関連する情報を提供します。これは説得力のある文章を書く練習であり、承認者にあなたの変更が受け入れられるべきだと納得させるためのものです。

説明文には、問題の原因、その解決方法、そしてどのように検証したかを記載します。代替設計案やそれがなぜ却下されたのか（例：リスクが高すぎるため）といった情報もここに含めるべきです。

変更前後のスクリーンショットや、単体テストなどの関連ドキュメントが完了していることを示す情報も重要です（出典）。リリースに近づくほど、このようなドキュメントの要件は厳しくなる傾向があると感じます。

コードコメント — コードの「使い方」を説明する永続的な情報

一方、コード内のコメントはコードそのものについて語るためのものです。この関数を正しく呼び出す方法、特定の前提条件の有無、といった情報が該当します。これらの情報は永続的であり、プルリクエストが完了した後も引き続き有用であり続ける必要があります。

コード内のコメントはコードそのものについて語るものです。この関数を正しく呼び出す方法は何ですか？特定の前提条件はありますか？この情報は永続的です。

例えば、「この関数が受け入れるJSONスキーマは〈ここ〉に文書化されています」といったコメントは、コード内に記述するべきです。これは関数の正しい使い方を説明する情報であり、時間の経過とともにその有用性が失われることはありません（出典）。

PR説明とコードコメントの違い：具体例で理解する

Chen氏は、実際のコメントを例に、どちらに記述すべきかを解説しています。以下にその違いをまとめました。

「関数のすべての呼び出しをチェックし、間違ったフラグを渡していたのはこれだけでした」というコメントは、PRの説明に含めるべきです。これは、レビュー時点での検証結果であり、この主張はその時々でしか有効ではありません。もし後日、別の開発者が誤ったフラグを渡す新しい呼び出しを追加した場合、その主張はもはや真実ではなくなってしまうからです（出典）。

個人的には、AIコーディングツールが生成するプルリクエストの品質を向上させる上でも、この区別は非常に重要だと感じます。Claude Code のようなツールを使ってコードを生成する際にも、PRの説明は人間がしっかり補完する必要があるでしょう。

AIが生成したコードの背景や意図、なぜその実装を選択したのかといった「Why」の部分は、現状では人間が補足するのが適切だと考えています。AIが自動で完璧なPR説明まで生成できるようになるには、もう少し時間がかかりそうです。