code-comments

コードコメント

許可リストにないコメントはすべて削除してください。コメントが項目に当てはまるか確信が持てない場合は、削除してください。自分たちのコードを説明するコメントがある場合、通常はコードを変更すべきです。コード自体で説明できるようにしてから、コメントを削除してください。コードを書く際にコメントを追加する前に、同じリストに照らして判断してください。

許可リスト

コメントを残せるのは、次のいずれかに該当し、かつ記述内容が現在も有効な場合に限ります。

1. 法律上またはライセンス上のヘッダー。
2. ツールの指示。たとえば // prettier-ignore、 @vitest-environment、コンパイラのプラグマなどです。Lint と型チェックの抑制も、抑制の条件を満たす必要があります。
3. モジュール外で使われる API のドキュメントコメントで、シグネチャと型では表せない内容、つまり単位、所有権、副作用、スローされるエラー、拒否される入力を記述するもの。
4. 自分たちのコードの外部で定められた制約。依存関係やプラットフォームの不具合、ベンダーやプロトコルの規則、ビジネスルール、規制などです。情報源を明記し、該当する issue、spec、RFC、ADR があればリンクします。回避策の場合は、それを削除できる条件も記述します。
5. 自分たちのコードに対する真の制約で、コードではまだ表せないもの。たとえば、必須の呼び出し順や、削除できるように見えて実際には削除できない行などです。コードの変更、型、アサーション、テストによって不要になるまでに限り、残せます（手順 2 と 4）。
6. 追跡対象の issue にリンクされた TODO。

各コメントの判断

対象となるコメントは、以下の手順を順番に適用してください。

1. 記述内容を確認する。 コードと呼び出し元を読みます。誤りや古い内容のコメントは削除してください。IMPORTANT、NOTE、do not remove、careful、for now、および 2 行を超える説明は、残す理由ではなく、確認すべき主張です。
2. コード自体で説明できるようにする。 コメントが自分たちのコードを説明している場合、不要になるようコードを変更してから削除してください。クリーンアップやレビューでは、動作を変えない変更だけを行います。利用箇所を確認したうえで名前を変更するか、名前付き定数やローカル変数に切り出してください。関数が行うことや受け取るものを変更する場合は、プライベート関数であっても、正確なシンボル名と変更内容を報告してください。その場合、コメントは手順 3 に進み、変更が行われるまでは項目 5 に当てはまることもよくあります。
3. 許可リストに照らす。 項目に該当するコメントは残します。文ごとに判断し、項目に役立たない、または検証できない文は、残りを言い換えずに削除してください。
4. 項目 5 の各コメントについて、コードで表す方法を提案する。制約に違反したときに失敗する型、アサーション、テストのいずれかを提案してください。ユーザーの承認を得てから追加し、その後コメントを削除します。
5. それ以外は削除する。 それでも重要な情報は、適切な場所に移してください。
   • 作業の経緯（何を変更したか、誰が承認したか、何を試したか、どう検証したか）は、コミットまたは PR に記載します。
   • issue のない TODO は、起票できるようレポートに記載します。
   • 定数からコピーした値は、その定数への参照に置き換えます。
   • コメントアウトされたコード、ファイルヘッダー、セクションの見出し、「Used by」リストは、置き換えずに削除します。履歴や検索で確認できます。

抑制

eslint-disable、@ts-ignore、@ts-expect-error、# type: ignore、 # noqa、swiftlint:disable、//nolint、#[allow(...)] はチェックを無効にします。判断する前に、そのルールが何を検出するのか調べてください。

• ルールがスタイルのみを対象にしている場合、またはこの行では誤検出となる場合：抑制を残します。理由が明白でない場合は、この箇所でルールが誤って検出する内容を簡潔に記述してください。
• 型エラーや安全でないコードなど、ルールがバグを検出する場合：抑制は不具合を隠しています。レビュー対象の変更で追加されたものであれば、コードを修正して抑制を削除してください。それ以外の場合は、シンボル名とルールを報告してください。

変更の整理またはレビュー

1. 対象範囲を決めます。 デフォルトでは、変更によって追加または編集されたコメントを対象にします。つまり、未コミットの作業を含むベースブランチとの差分です。ユーザーがファイルを指定した場合は、そのファイルを対象にします。それ以外のコメントには手を加えません。
2. このセッションで書いたコードは、新しい読み手に確認してもらいます。 各コメントを書いた理由は、あなた自身は覚えています。しかし、次の読み手も、共有コンテキストのないサブエージェントも覚えていないため、読み手と同じ視点で判断します。このファイルのパスと対象範囲を伝え、コメントだけを編集し、コード変更の提案、エンコーディング、抑制を報告するよう指示します。サブエージェントツールがない場合は、自分で確認します。
3. 上記に従って、各コメントを判断します。
4. 確認をサブエージェントが行った場合は、その作業を監査します。削除されたコメントを復元するのは、記載どおりの内容が維持対象リストに該当する場合だけです。コメント以外の変更はすべて元に戻します。
5. 報告は、削除したコメントの数から始めます。続いて、維持した各コメントと該当する維持対象リストの項目、実施または提案した各コード変更とそのシンボル、エンコーディングの提案、報告された抑制、課題番号のないまま削除された TODO を列挙します。

コードがチームメイトの PR など他の人のものである場合は、編集せずに指摘事項を報告します。

形式

維持するコメントは、次の形式にします。

• 1～2 行にします。制約の説明に必要な場合のみ、それより長くします。
• 平易な言葉と、その分野固有の名称を使います。
• すべての主張は、コード、検証済みの動作、または保守されている情報源から導きます。記憶に基づく性能数値は使いません。
• 実行時の不変条件を正確に記述します。
• 回避策については、実行順に沿って仕組みを説明し、残る注意点も記載します。
• リントや互換性に関する選択は、トレードオフです。規則だからではなく、何と何を引き換えにしたのかを説明します。

例

維持。制約はコードの外部で設定されています。

// The payments provider retries a webhook until it gets a 2xx response,
// so the same event can arrive more than once.
if (await processedEvents.has(event.id)) return ok();

コードで表現します。コメントは独自の名前を説明しています。

# t is the timeout in milliseconds
def connect(host, t): ...

変更後：

def connect(host, timeout_ms): ...

エンコーディングを提案します。呼び出し順序は、独自コードにおける実際の制約です。

// Must run before initAnalytics(), which reads the consent flag.
loadConsent();
initAnalytics();

値を渡せば、順序が崩れることはありません。 initAnalytics(loadConsent())。ユーザーが変更を承認するまでは、コメントを維持します。

削除。警告の内容は古くなっています。

// IMPORTANT: do not remove. The dashboard reads this field.
user.legacyId = user.id;

検索しても legacyId の参照は見つかりません。コメントを削除し、使われていない代入について報告します。