开发与测试
code-comment
ソースコード中のコメントを書く時の心得。コメントに何を書き、何を書かないかの判断基準と、置く位置、日本語の文体を定める。 ソースコードのコメントを書く時、直す時、レビューする時に読み込む。
shokai · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add shokai/agent-skills --skill code-comment技能说明
name: code-comment description: >- ソースコード中のコメントを書く時の心得。コメントに何を書き、何を書かないかの判断基準と、置く位置、日本語の文体を定める。 ソースコードのコメントを書く時、直す時、レビューする時に読み込む。
ソースコード中のコメントを書く時の心得
ソースコードのコメントを書く時、直す時、レビューする時は、以下の基準に従う。
心得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概要欄に書く。コードは最終形態だけを表す
- 相対的な時点を参照しない。「従来は」「今までは」は、mergeされた後に基準の時点が失われ、意味を持たなくなる。コメントは現在のコードの意図だけを述べる
心得3. 公開されるコードに、非公開の実装を書かない
公開されるrepositoryやpackageのコメントに、非公開のコードの実装の機構を書かない。file path、関数名、middleware名がこれに当たる。
外から観測できる仕様を根拠にした理由は、書いてよい。「URLのタイトル部分に生の / が来ると、サーバーが拒否するので、ここで正規化する」は観測できる仕様で、サーバーのどの関数が何をしているかは実装の機構である。
心得4. 削る事を目的にしない
読み手が実装を読む時に要る情報は書く。既存のコメントを点検した結果、大半が正当な意図の説明で、現状維持になる事もある。
- 日時等の整形関数には、返す文字列の実例を書く。
// 2026/09/12 05:03:21 UTCという形式を返すのように書く。整形のオプションの羅列から、出力の形は読み取れない - 高階関数の使用例は残してよい。
// 使用例: rateLimit({ cost: 1 }).or(fallbackHandler)のように書く。関数の冒頭にvalidationやsetupがあり、返り値が更にchainできる事が定義から分かりにくい時に役立つ - 特定のオプション値にまつわるgotchaは、関数の上にまとめず、該当する行の行末に置く
心得5. 日本語のコメントの文体
- 目的は完全な節で言い切る。「〜できるよう」「〜で使うため」と書く。「〜用に、」のような体言止めの断片にしない
- 目的の述語を曖昧な語にしない。「highlightが当たるよう、Xを保持する」ではなく「highlightを判定できるよう、Xを保持する」と書く。「当たる」では、何が成立する事なのかを言い切れていない
- 和文と、英字やコードの識別子との間に空白を入れない。
Modal を <dialog> にではなくModalを<dialog>にと書く。react-bootstrap Modalのような英単語同士の空白は残す - 行コメントの文末に
。を付けない。複数の文を区切る途中の。は残す - 折り返さず1行にまとめる
- 文意を裏返しただけの括弧注記を削る。「実際に書かれた表記を保持する(正規化後ではない)」の括弧の中は、前半が言えた時点で自明である