writing-code-comments

コードコメントの書き方

コメントを追加または編集する前に、これを実行してください。デフォルトはコメントなしです。わかりやすい名前が付いた優れたコードは、それ自体で意味のほとんどを伝えます。コメントは、コードでは伝えられないことを読者に伝えるときだけ、その存在価値を持ちます。

ゲート: 1 つの問い

コメントを書く前に、次に答えてください。

これは、コード自体が伝えない何を、将来の読者に伝えるのか？

答えが「コードがしていることの言い換え」なら、それを削除してください。代わりに変数の名前を変えるか、関数を抽出してください。

残す価値のあるコメントは、コードでは答えられない why に答えます。

• ✅ # ATOMIC_REQUESTS is off, so wrap the two writes that must commit together
• ✅ // Stripe sends the amount in cents; the rest of our system uses dollars
• ✅ # Kept in sync with the enum in migrations/0042; update both

これらは削除する

コードを言い換えるだけのナレーション

• ❌ counter += 1 の上にある # increment the counter
• ❌ for user of users の上にある // loop over users
• ❌ return result の上にある # return the result

あるブロックを追うのにナレーションが必要なら、修正すべきはコメントではなく、より小さな関数とより良い名前です。

変更履歴とチャットの文脈

コードがどうやってここに至ったかを記録しないでください。それはコミットメッセージと PR の説明に属するもので、そこでは差分に紐付き、検索も可能です。ソースコード内では、すぐに古くなるノイズにすぎません。

• ❌ # previously used a set here, switched to a list for ordering
• ❌ // per PR #1234 / # as discussed / # changed because the old way broke
• ❌ # AI: generated this helper / // agent: refactored
• ❌ マイグレーションからずっと後に残された # TODO(2024-01): remove after migration

賞味期限のある測定値と現状のスタンプ

測定された所要時間、件数、レートは静かに腐っていきます。それらを更新させるものは何もなく、腐った数値は次にタイムアウトやシャード数を検討する人を誤らせます。「currently」/「today」といった但し書きも同じです。それらがなくても文は同じ事実を述べているからです。その数値が表していた持続的な関係を述べてください。

• ❌ # skip the ~20 min build、ただし持続的な事実はビルドが高コストであること
• ❌ # ci-backend runs ~28m, so 60m ≈ one red result の代わりに「最も遅いワークフローの 1 回の完全な実行を超える長さに設定」
• ❌ # no story currently opts into webkit snapshots、ただし「currently」を外しても同じ事実を述べている
• ❌ # ~20 minutes in June, past 25 by July、傾向のナレーションは変更履歴だから

残す数値:

• 日付付きのスナップショット: # as of August 2024, Homebrew ships 4.13.2（日付があることで古さが可視化されます）
• 隣接するコードリテラルの再掲: 300 の隣の # runs that took >5 min (300 seconds)（コードとともに更新されます）
• プラットフォームの定数: # GitHub's comment size limit (~64KB)
• 目標または予算: # Target: ~15 min per shard（測定値ではなくポリシー）
• 引用された根拠: # 30% peak memory observed on 16-core runs (#46853)（リンクが日付を示します）

コメントアウトされたコード

削除してください。再び必要になれば、バージョン履歴に残っています。コメントアウトされたコードは次の読者にとって曖昧で、メモなのか、ロールバック計画なのか、それとも事故なのかを判別できません。

冗長な docstring と型の再掲

• ❌ 関数名を散文で繰り返す docstring: get_user_by_id に対する """Gets the user by id."""
• ❌ すでに型が付いているフィールドに対する # type: string
• ❌ Python のテストの doc コメント（リポジトリの規約ではなし。テスト名がそれを示しています）

これらは残す

• コードからは明らかでない why: ワークアラウンド、パフォーマンスのトレードオフ、仕様の癖、順序の制約。
• 別の場所にある結果についての warning: 「これを変更するとキャッシュキーが壊れる」「呼び出し元はこれがソートされていることに依存している」。
• 読者がリポジトリから再構築できない文脈への pointer: 仕様、チケットへのリンク、または意外な値が選ばれた理由。

スタイル

コメントは、技術ドキュメントを書くときと同じように書いてください。明示的かつ正確に。読者が推測しなくても済むように、根拠を述べてください。長さはどちらの方向でも目標ではありません。簡潔に見せるためにコメントを切り詰めたり、徹底しているように見せるために水増ししたりしないでください。言うべきことを述べて、そこで止めてください。

• 明示的かつ技術的に。 原因と結果を述べてください。実際の条件、値、結果を明記してください。読者がヒントからあなたの推論を再構築しなくても済むようにしてください。
• 主に ASD-STE100 簡易技術英語を使用してください。 能動態、単純な時制、1 文につき 1 つのアイデア、一貫した用語を使用してください。
• 長さは内容に従わせてください。 1 行で足りるなら 1 行で構いません。推論にもっと必要なら、もっと使ってください。簡潔さも長さも目標ではありません。
• em ダッシュは使わないでください。 避けるべき特徴は、ダッシュでつながれた切り詰めた 2 部分のフレーズです。たとえば # do the thing — it's faster のようなものです。代わりに本当の接続語を使ってください（「because」「so that」「which means」「to avoid」など）。
• 何をではなく、なぜを説明してください。 何はコードの中にありますが、なぜは通常そこにはありません。
• コードを移動またはリファクタリングするときは、既存のコメントを保持してください。ただし、その変更によってコメントが誤りになる場合は除きます。関数を移すという理由だけで、既存の why を落とさないでください。
• 周囲の密度に合わせてください。 コメントがまったくないファイルのすべての行にコメントを追加しないでください。よくコメントされたモジュールを丸裸にしないでください。

em ダッシュの修正は、接続語であり、より多くの言葉ではありません。ダッシュがなくなれば、短いコメントで構いません。

• ❌ # batch here — avoids N+1
• ✅ # batch here to avoid an N+1 against posthog_organizationmembership

コメントしたくなったとき

順に試してください。(1) より良い名前、(2) より小さな関数、(3) 型。それらのいずれも意味を担えない場合にのみ、コメントに手を伸ばしてください。