{"slug":"shokai-code-comment","name":"code-comment","description":">-","long_description":"---\nname: code-comment\ndescription: >-\n ソースコード中のコメントを書く時の心得。コメントに何を書き、何を書かないかの判断基準と、置く位置、日本語の文体を定める。\n ソースコードのコメントを書く時、直す時、レビューする時に読み込む。\n---\n\n# ソースコード中のコメントを書く時の心得\n\nソースコードのコメントを書く時、直す時、レビューする時は、以下の基準に従う。\n\n## 心得1. コードから読めない事だけを書く\n\nコメントに書いてよいのは、コードを読んでも分からない事だけである。非自明な制約、invariant、隠れ仕様、gotcha、特定のbugへのworkaroundがこれに当たる。なぜそうするかという意図も書いてよい。\n\nコードや配置から読み取れる事を、言葉でなぞらない。配置とは、ファイルの位置、関数名、周辺のコードの事である。自明な説明は実装との二重管理になり、コードを変更した時の更新漏れの原因になる。読み手には、コードと違う事を言っているかもしれないと疑う負担をかける。\n\n- 直下の処理を言い直さない。`text.replaceAll('\\0', '')` の直上に `// NULを弾く` と書かない\n- 配置が既に表している前置きを書かない。特定の機能専用のディレクトリにある定数に「この機能専用の上限」と書かない。その場所に他の機能の上限があるはずがない\n- 意図を書く前に、その動機がコードの式から読めないか確かめる。読めるなら書かない。書き残すなら、commit messageかPR概要欄に置く。メールの件名に `(test ...)` を付けるコードは、その式だけで、test送信を区別する意図が読める\n\n書いてよいコメントの例を挙げる。\n\n- `// TextDecoderが既定でBOMを除去する`\n- `// 上流APIの制約で、書き込みはPAT認証のみ`\n- `// .trim()ではなく末尾改行のみ除去する。先頭空白は保持したい`\n\n## 心得2. 意図の説明に見えても、書かない物がある\n\n- defaultの帰結に、理由を書かない。理由が要るのは、defaultから逸脱した時だけである。APIレスポンス等の元データに無いfieldを持たせないのは当然の帰結で、理由は要らない。元データに無いfieldをあえて合成して持たせる時に、理由を書く\n- 経緯や履歴を書かない。「これはbugだった」「Aを試したがBにした」は、commit messageやPR概要欄に書く。コードは最終形態だけを表す\n- 相対的な時点を参照しない。「従来は」「今までは」は、mergeされた後に基準の時点が失われ、意味を持たなくなる。コメントは現在のコードの意図だけを述べる\n\n## 心得3. 公開されるコードに、非公開の実装を書かない\n\n公開されるrepositoryやpackageのコメントに、非公開のコードの実装の機構を書かない。file path、関数名、middleware名がこれに当たる。\n\n外から観測できる仕様を根拠にした理由は、書いてよい。「URLのタイトル部分に生の `/` が来ると、サーバーが拒否するので、ここで正規化する」は観測できる仕様で、サーバーのどの関数が何をしているかは実装の機構である。\n\n## 心得4. 削る事を目的にしない\n\n読み手が実装を読む時に要る情報は書く。既存のコメントを点検した結果、大半が正当な意図の説明で、現状維持になる事もある。\n\n- 日時等の整形関数には、返す文字列の実例を書く。`// 2026/09/12 05:03:21 UTCという形式を返す` のように書く。整形のオプションの羅列から、出力の形は読み取れない\n- 高階関数の使用例は残してよい。`// 使用例: rateLimit({ cost: 1 }).or(fallbackHandler)` のように書く。関数の冒頭にvalidationやsetupがあり、返り値が更にchainできる事が定義から分かりにくい時に役立つ\n- 特定のオプション値にまつわるgotchaは、関数の上にまとめず、該当する行の行末に置く\n\n## 心得5. 日本語のコメントの文体\n\n- 目的は完全な節で言い切る。「〜できるよう」「〜で使うため」と書く。「〜用に、」のような体言止めの断片にしない\n- 目的の述語を曖昧な語にしない。「highlightが当たるよう、Xを保持する」ではなく「highlightを判定できるよう、Xを保持する」と書く。「当たる」では、何が成立する事なのかを言い切れていない\n- 和文と、英字やコードの識別子との間に空白を入れない。`Modal を