superior-comments

優れたコメント

コードでは明確に表現できない情報を、コメントで伝えます。コメントのみを扱うタスクでは、実行可能なコード、コメント以外の書式、インポート、設定、生成ファイルは変更しないでください。

説明に必要なコメントは残す

• 意図や、一見してわかりにくい不変条件
• 一見するとより単純な方法が安全ではない理由
• プロトコル、互換性、セキュリティ、法的な制約
• 単位、座標系、所有権、ライフサイクル、順序に関する前提
• 安全に削除できるだけの背景情報を含む回避策
• ドキュメント生成ツールが参照する公開 API の契約
• 条件、担当者や参照先、または具体的な次のステップが明確な TODO（情報が得られる場合）

ライセンスヘッダー、帰属表示、生成ファイルに関する警告、リンターの指示、移行メモ、運用手順は、古くなっていると確認できない限り削除しないでください。

ノイズを削除または書き換える

• 見えている構文を一行ずつ説明するコメント
• 飾りの区切りや、空のセクション見出し
• エージェントの作業手順を告げるコメント
• 「後で改善する」などの曖昧な TODO
• 生成作業の終了位置を示す結論や署名
• ドメイン上の意味を加えない絵文字や大げさな表現
• 実装と矛盾する古い記述

まとまりのあるブロックの理由を説明するコメントは一つにまとめ、文ごとにコメントを付けないでください。同義語を使い分けるより、正確なドメイン用語を繰り返すほうが明確です。

コードベースに合わせる

リポジトリで使われている言語、コメント構文、ドキュメント形式、標準的な語調を維持してください。コメントは、そのコメントが制約する動作の近くに置いてください。コードを読むことしか許されていない範囲でコメントに誤りがある場合は、現在の動作を説明する内容に修正してください。動作に合わせて、黙ってコードを変更してはいけません。

検証する

差分を確認し、変更がコメントのみに限られていることを確かめてください。コメント構文がコンパイル、生成ドキュメント、指示、ツールに影響する場合に限り、対象を絞ったフォーマッターやパーサーを実行してください。運用上の役割がないと確認できず、曖昧なコメントを残した場合は報告してください。