ソースコード中のコメントを書く時の心得

ソースコードのコメントを書く時、直す時、レビューする時は、以下の基準に従う。

心得1. コードから読めない事だけを書く

コメントに書いてよいのは、コードを読んでも分からない事だけである。非自明な制約、invariant、隠れ仕様、gotcha、特定のbugへのworkaroundがこれに当たる。なぜそうするかという意図も書いてよい。

コードや配置から読み取れる事を、言葉でなぞらない。配置とは、ファイルの位置、関数名、周辺のコードの事である。自明な説明は実装との二重管理になり、コードを変更した時の更新漏れの原因になる。読み手には、コードと違う事を言っているかもしれないと疑う負担をかける。

• 直下の処理を言い直さない。text.replaceAll('\0', '') の直上に // NULを弾く と書かない
• 配置が既に表している前置きを書かない。特定の機能専用のディレクトリにある定数に「この機能専用の上限」と書かない。その場所に他の機能の上限があるはずがない
• 意図を書く前に、その動機がコードの式から読めないか確かめる。読めるなら書かない。書き残すなら、commit messageかPR概要欄に置く。メールの件名に (test ...) を付けるコードは、その式だけで、test送信を区別する意図が読める

書いてよいコメントの例を挙げる。

• // TextDecoderが既定でBOMを除去する
• // 上流APIの制約で、書き込みはPAT認証のみ
• // .trim()ではなく末尾改行のみ除去する。先頭空白は保持したい

心得2. 意図の説明に見えても、書かない物がある

• defaultの帰結に、理由を書かない。理由が要るのは、defaultから逸脱した時だけである。APIレスポンス等の元データに無いfieldを持たせないのは当然の帰結で、理由は要らない。元データに無いfieldをあえて合成して持たせる時に、理由を書く
• 経緯や履歴を書かない。「これはbugだった」「Aを試したがBにした」は、commit messageやPR概要欄に書く。コードは最終形態だけを表す

心得3. mergeされた後に、そのファイルだけを読む人に向けて書く

コード内のコメントの読者は、pull requestのレビュアーだけでなく、merge後の未来のコントリビューターも含まれる。「従来は」「今までは」のように相対的な時点を参照すると、mergeされた後に基準の時点が失われ、意味を持たなくなる。「matchする文字列は変わらない」のように、比べる相手がmerge後のコードに存在しなくなる文も同じで、何を指すのか後から意味不明になる。「〜のまま」「〜なくなった」「〜ようになった」にも、変更前との比較が隠れている事がある。コメントは現在のコードの意図だけを述べる。pull requestのレビュアーだけに向けた説明には、GitHubのコメント機能を使う。

• 変更前との比較を、今のコードの性質として言い直す。「matchする文字列は変わらない」ではなく「matchする文字列は狭めない」と書く。testのコメントも同じで、「先読みが外れると」ではなく「先読みが無いと」と書く
• 仕組みの説明より、読む人が検索できるテクニカルタームと、守るべき制約を書く。// 先読みはReDoS対策。後ろのpatternを変える時は先読みも合わせる のように書く
• 書き終えたら、PR概要欄やcommit messageを見ずに、そのファイルだけを開いた人として読み直す

心得4. 公開されるコードに、非公開の実装を書かない

公開されるrepositoryやpackageのコメントに、非公開のコードの実装の機構を書かない。file path、関数名、middleware名がこれに当たる。

外から観測できる仕様を根拠にした理由は、書いてよい。「URLのタイトル部分に生の / が来ると、サーバーが拒否するので、ここで正規化する」は観測できる仕様で、サーバーのどの関数が何をしているかは実装の機構である。

心得5. 削る事を目的にしない

読み手が実装を読む時に要る情報は書く。既存のコメントを点検した結果、大半が正当な意図の説明で、現状維持になる事もある。

• 日時等の整形関数には、返す文字列の実例を書く。// 2026/09/12 05:03:21 UTCという形式を返す のように書く。整形のオプションの羅列から、出力の形は読み取れない
• 高階関数の使用例は残してよい。// 使用例: rateLimit({ cost: 1 }).or(fallbackHandler) のように書く。関数の冒頭にvalidationやsetupがあり、返り値が更にchainできる事が定義から分かりにくい時に役立つ
• 特定のオプション値にまつわるgotchaは、関数の上にまとめず、該当する行の行末に置く

心得6. 日本語のコメントの文体

文体はkuden:writing skillの基準に従う。コメントでは、さらに次の2点を守る。

• 行コメントの文末に 。 を付けない。複数の文を区切る途中の 。 は残す
• 折り返さず1行にまとめる