code-comments

コードコメント

コメントはコンパイルされず、テストで検証されることもないため、ファイルをまたいで増えながら、コードとのずれが生じていきます。コードだけでは伝えられない情報を含むコメントは残し、それ以外は削除してください。

言語は問いません。ルールは //、#、/* */、``、docstring、PHPDoc、JSDoc のいずれにも当てはまります。意見が異なる場合は、プロジェクトの CLAUDE.md / AGENTS.md が優先されます。また、周囲のファイルですでに使われている慣習も優先されます。

1. 判断基準

まずコードを書きます。初めて読む人のつもりで読み返します。コードだけでは分からないことに限り、コメントを追加してください。

コメントを残す価値があるのは、次のいずれかを伝える場合です。

• コードからは分からない理由。 もっとも分かりやすい方法ではなく、この方法を選んだ理由。
• ファイルの外部にある制約。 センチネル値を返す API、大文字と小文字を区別せず照合するカラム、基本 CSS を提供しないライブラリなど。
• 意図的な例外。 何が壊れたかを知るまでは、間違っているように見えるコード。
• 境界。 サニタイズを行う唯一の関数、意図的に定時間で処理する比較など。
• 情報源への参照。 仕様の段落、準拠対象のレガシー動作、すでに追跡されている作業の課題番号。

それ以外はすべて削除してください。コードが何をするかは、コード自体が示しています。

// A node id in this set is collapsed; its children are dropped from the rows.
const collapsed = reactive(new Set<number>());

名前が示し、型が示し、使い方が示しています。この行は削除してください。

2. コメントでコードを正当化しているなら、コードを修正する

コードが許容できる理由を段落で説明する必要のあるコメントは、問題を記録しているのであって、説明しているのではありません。名前付き関数に切り出す、変数名を変更する、分岐を分割するなどしてください。混乱がなくなれば、コメントも不要になります。

ブロックの内容を説明するコメントにも同じことが言えます。20 行のコードの前にある // 行を組み立ててから、並べ替える は、その名前を持つ 2 つの関数に分けるべきです。

3. 見つけたら削除するコメント

次の行を言い換えているもの。 コメントとコードが同じことを述べているため、どちらか一方が無償の保守作業になります。

すぐ下にある項目を列挙しているもの。 データクラスのフィールドを列挙するドキュメントコメント（「識別情報、日付範囲、アーカイブ済みかどうか」など）は、10 行下にあるプロパティの一覧を繰り返しており、フィールドが追加された時点で古くなります。

関数内のセクション見出し。 // --- validation --- は、本来関数呼び出しにすべき区切りを示しています。

コメントアウトされたコード。 バージョン管理で保持されます。後に残された空の try { /* ... */ } catch {} も含めて削除してください。

内容とずれてしまったコメント。 コードを移動または並べ替えると、上にあるコメントはそのまま残り、新しい隣接コードを説明してしまうことがよくあります。コメントの主張と、その下に実際にあるコードを照らし合わせてください。別の場所に属するなら移動し、対象がなくなっているなら削除してください。

5 つのファイルに同じブロックがあるもの。 コピーされた定型文は読まれなくなります。各箇所で 1 行にまとめるか、説明対象となる共有部分にまとめてください。

4. 長いコメントを短くする

長いコメントの多くは、1 つの理由と、それを言い換えた記述で構成されています。理由を残してください。

理由から導かれる結果は削除してください。検討対象にならなかった代替案は削除してください。最初の文を言い換えている 2 文目は削除してください。形容詞は削除してください。

// Rounded to roughly ten meters: two people in the same street share a range, and
// a rounding difference should not cost another request. The rounded position is
// what gets measured as well, so the polygon under a key is the one that key
// describes rather than whoever asked for it first.

これは次のようになります。

// Rounded to roughly ten meters, so two people in the same street share a range. The
// rounded position is measured as well, so a key describes the polygon under it.

どちらも不可欠な 2 つの文です。丸めを行う理由と、丸めた値も測定対象にする理由を説明しています。

1 行を目指してください。2 文目が 1 文目にない情報を伝える場合は、2 文にします。現在のコードが一致させる必要のある過去のカラムなど、明確に別の懸念事項を扱う場合に限り、2 段落目を使ってください。

5. Doc ブロック

プロジェクトであらゆるクラスや関数をドキュメント化している場合（PHPDoc、JSDoc、docstring）は、その慣習に従います。ブロックは残し、短くまとめます。

説明には、名前だけでは伝わらないことを書きます。 その要素の目的と、呼び出し側が知っておくべきことを1、2文で記します。名前を文章に言い換えているだけなら、説明を削除したほうがよいでしょう。

タグには型と名前を記し、説明文は加えません。 @param int $limit だけで十分です。シグネチャからは分からない情報を伝える場合に限り、単位、形式、ドメイン用語、null の意味、許容範囲などを追記します。

@param int $requestId                  // nothing to add
@param string $date Date in `Y-m-d` format.
@param int|null $branchId Narrows to this branch and everything below it.
@param float $wtf The werktijdfactor, not the raw stored integer.

配列やオブジェクトの形状は、記載する価値があります。 @return array{items: Row[], total: int} や型付きジェネリックのほうが、同じ形状を文章で説明するより適切です。

呼び出し側の事情は説明しません。 どの画面から呼び出されるか、どのタブを支えるか、どのリリースで追加されたか。こうした情報はリファクタリング後には残りません。代わりに、動作を明記します。

6. 必ず残すもの

• 担当者と条件が明記された TODO やメモ： // todo(Bas): drop this once frontend 1.0 is gone. 名前やきっかけのない TODO は、いつまでも解決されないコメントです。
• ライセンスおよび著作権ヘッダー： プロジェクトで使用している場合。
• セキュリティ境界。 比較を定時間で行う理由や、呼び出し箇所ではなくここで値をエスケープする理由。
• 回避策。 回避策が不要になるバージョンや条件も記します。Node < 20、until the API returns a proper status。
• 外部参照。 仕様書の段落、cao や規制の条項、ベンダー固有の挙動、上流のバグへのリンク。
• 意図的に踏襲しているレガシー動作。 すでに存在しないカラムやエンドポイントも含みます。コードからは推測できません。

7. 配置と言語

コメントは説明対象のすぐ上に、同じインデントで記述します。宣言のまとまりの上にあるコメントは、そのまとまり全体を説明するものです。特定の宣言についてのコメントなら、その宣言の直前に移します。

コメントは、コードベースで使われている言語とスペルの慣習に合わせて記述します。周囲のコメントの密度にも合わせましょう。コメントがないファイルは、コードにどれだけ説明が必要かを示しています。

8. 既存ファイルのレビュー

まずコメントを読んでからコードを読み、それぞれのコメントを今も書くかどうか確認します。次の3つの手順で、ほとんどの問題を見つけられます。

1. 直下の行ですでに説明されているか。該当する場合は削除します。
2. 直下の行についての説明か。該当しない場合は移動するか削除します。
3. 語数を半分にしても理由が伝わるか。伝わる場合は削ります。

コメントが多いファイルでは、コメント行の3分の1から半分を削除するのが普通です。何も削除されなかった場合、ファイルがすでに簡潔だったか、見直しが不十分だったかのどちらかです。

関連スキル

• unslop - 同じ考え方を文章に適用し、冗長な部分を削って要点を残します。
• リポジトリの CLAUDE.md / AGENTS.md - コメントの言語、Doc ブロックの要件、ヘッダーの慣習に関するプロジェクトのルールです。このページの既定のルールより優先されます。