melech-smart-comments

スマートなコメント

あなたは、このコードを最初に読むことがよくあります。人間のチームメイトのような経験の積み重ねはありません。ある関数が今の形になった原因のインシデントを経験していませんし、コードの形だけから地雷の存在を嗅ぎ取ることもできません。

コメントは、コードに最も近い仕様のレイヤーです。コメントは、モデルが次のトークンを生成する前に読む最後のものであり、人間が制約、警告、意図を伝える最も手軽でシグナルの強い手段です。コメントはそのように扱ってください。

このスキルでは、新しいコメントの書き方と、既存のコメントの扱い方を定めます。

コメントを書くとき

次のいずれかに該当する場合は、インラインコメントを書いてください。それ以外の場合は書かないでください。

1. 地雷。 間違っている、冗長である、または削除できそうに見えるものの、実際にはそうではないコードです。理由を述べてください。過去のバグ、順序に関する制約、外部システムの癖など、次に読む人（人間またはエージェント）が手を加える際のリスクを理解できるようにします。
2. 自明ではない理由。 よりすっきり見える別案ではなく、選択した方法を採用した理由がある場合は、そのトレードオフを明示してください。「X もできますが、高負荷時には Y が起きます」は、判断に不可欠な情報です。それがなければ、次に読む人は X を試すでしょう。
3. 隠れた不変条件と契約。 型、名前、関数本体だけでは分からない暗黙の前提です。呼び出し間の順序、冪等性の保証、呼び出し元が事前に設定しておくべき状態、同時に値が設定されていなければならないフィールドなどが該当します。
4. 回避策。 外部システムのバグ、競合状態、一時的なバージョン固定、上流の修正を待つポリフィルやハックなどです。該当する問題がある場合は、リンクするか、名前を記載してください。

コメントを書かないとき

次の場合はコメントを書かないでください。

• コードが何をするかを説明していて、識別子からすでに分かる場合。// increment counter を counter++ の上に書くのはノイズです。
• 現在のタスク、チケット、PR、作成者、レビューラウンドに言及している場合。それらはコミットメッセージや PR の説明に記載するものです。コードに残すと古くなります。
• バナー、セクション区切り、または関数シグネチャの言い換えである場合。
• リファクタリング後もコード自体が確実に意図を示せる場合。名前の変更でコメントが誤りになるなら、そのコメントは冗長です。

関数名と引数から理由が明らかな場合、そのコメントはスペースを使う価値がありません。

書き方

• インラインで。 コメントが保護する行のすぐ上か横に置きます。ファイルの先頭や外部ドキュメント、コミットメッセージには書きません。
• 短く。 制約や警告から始めます。前置きは不要です。
• 必要な場合は命令形で。 「X より先に実行する必要があるため、順序を変えないでください」は、「これは X より先に実行されます」よりも適切です。
• コストを明示する。 「この早期リターンを削除すると、修正した N+1 問題が再発します」は、「重要な早期リターンです」よりも有効です。
• 理由のつながりを補う。 見慣れない読者が、何を変更すると制約に違反し、何が壊れるのかを理解できるだけの因果関係を示します。「競合」「セキュリティ上の問題」「データ漏えい」といったラベルだけでは説明になりません。
• 3 行程度を目安にしつつ、無理に短くしないでください。 理由を保てる最短のコメントにします。それよりかなり長くなる場合は、制約がより明確に表れるようコードを記述してください。

既存のコメントを尊重する

このスキルが存在する理由は、このセクションにあります。

• 既存のコメントは、不要だと証明されるまではすべて重要なものとして扱ってください。 人間であれ過去のエージェントであれ、誰かがコストをかけて残したものです。そのコストには理由があったと考えてください。
• リファクタリング中にコメントを削除しないでください。 そのコメントが説明しているコードも削除する場合は除きます。コードを移動しただけでは、コメントを捨てる理由になりません。
• 「冗長に見える」だけでは、削除の正当な理由になりません。 コメントは、コード自体からはもう読み取れない過去のインシデントの痕跡を、唯一残している可能性があります。
• コメントが古い、または間違っているように見える場合は、ユーザーへの回答でその点を指摘してください。 何も言わずに修正または削除してはいけません。コメントが今も現状を反映しているか確認できるのは、ユーザーだけです。
• 口調や文体を変えるだけの目的で、コメントを書き換えてはいけません。 警告として書かれているなら、警告のままにしてください。

キャリブレーション例

悪い例 — コードにすでに書かれている内容を説明しています：

# Increment the retry counter
retries += 1

良い例 — 落とし穴を示しています：

# Do not switch to exponential backoff here; upstream rate-limits on burst, not on average.
retries += 1

悪い例 — 次のリファクタリングで陳腐化します：

// Added in PR #4821 by @alice to handle the new billing webhook
if (event.type === "invoice.paid") { ... }

良い例 — WHY を残しています：

// Stripe fires invoice.paid before invoice.finalized for auto-advancing subs; handle both orderings.
if (event.type === "invoice.paid") { ... }

悪い例 — 飾りにすぎず、意味のある情報を加えていません：

// ---------- Helpers ----------

良い例 — 暗黙の契約を明文化しています：

// Caller must hold s.mu. Returns the unwrapped value; safe only until the next Set().
func (s *state) peek() T { ... }

悪い例 — 失敗の内容を示すだけで、その理由を説明していません：

// Keep this order to avoid a race.
await save(job);
await publish(job);

良い例 — 順序を維持するために必要な、最小限の理由を示しています：

// Persist before publishing: a worker may consume immediately and must find the job.
await save(job);
await publish(job);

まとめ

コードは動きを示します。コメントは記憶を残します。その記憶が次の編集後も残るかどうかを最も頻繁に判断するのは、コードを読むあなたです。迷ったら、コメントを残して、それを削除すべきか人間に尋ねてください。