跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

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行にまとめる
  • 文意を裏返しただけの括弧注記を削る。「実際に書かれた表記を保持する(正規化後ではない)」の括弧の中は、前半が言えた時点で自明である