| name | code-naming |
| description | 関数名、メソッド名、クラス名、型名、変数名、定数名、ファイル名、ディレクトリ名などコード上の命名をレビューし、責務、抽象度、既存語彙、検索性、呼び出し側の読みやすさ、ユーザーの命名の好みに基づいて候補を出すときに使う。名前候補を比較したい、既存名を改善したい、命名の一貫性を確認したい、曖昧な名前、過度に汎用的な名前、コンテキストと重複した冗長な名前を直したいときに使う。 |
Code Naming
目的
コード要素の名前を、責務、抽象度、読み手の予測、既存コードの語彙に合わせて整える。
このスキルは命名だけを扱う。設計全体の妥当性、バグ、仕様違反、typo の検査は主目的にしない。
基本方針
- まず第一候補を示し、理由を短く説明する。
- 候補は原則 3-5 個に絞る。
- 呼び出し側から読んだときに自然な名前を優先する。
- 名前単体の説明力よりも、周辺コンテキスト込みで簡潔に読めることを優先する。
- ディレクトリ名、ファイル名、型名、メソッド名、変数スコープで既に伝わる情報を重ねない。
- 既存コードの命名規則、ドメイン語彙、prefix / suffix を優先する。
- 局所的に好みの名前でも、周辺の体系を崩すなら採用しない。
- 名前だけで解決できない責務の混ざり方がある場合は、命名候補より先にその懸念を明示する。
ユーザーの命名の好み
- 簡潔で、周辺コンテキストと情報が重複しない名前を好む。
- 名前単体で全部を説明しようとするより、置かれた場所と合わせて自然に読める名前を好む。
- 抽象的すぎる名前を避ける。
- ただし、コンテキストで十分に補える語は削る。例:
users/user_repository.go では UserRepository より Repository を候補に入れる。
- ディレクトリ名とファイル名で同じ語を重ねない。例:
repository/user_repository.go より repository/user.go や user/repository.go を優先する。
Manager, Handler, Processor, Service, Util, Data, Info のような汎用語は、責務を十分に絞れない限り避ける。- Boolean は肯定形で読む名前にする。例:
isEnabled, hasItems, canRetry
- 関数名とメソッド名は、処理内容が読める動詞句にする。
- クラス名、型名、インターフェース名は、責務や役割を表す名詞句にする。
- 実装詳細を名前に入れすぎない。ただし、境界、永続化方式、外部 API、非同期性など、呼び出し側の判断に必要な語は残す。
- 略語は、既存コードやドメインで定着しているものだけ使う。
- 迷ったら、将来検索しやすく、レビューで意図を説明しやすい名前を選ぶ。
- 検索性を理由に長くしすぎない。検索したい単位がディレクトリや型で既に絞れるなら、局所名は短くする。
見る観点
関数・メソッド
- 副作用があるなら動詞で始める。
- 値を返すだけなら、
get を乱用せず、取得コストや副作用の有無が伝わる名前にする。
- 条件判定は
is, has, can, should, needs などで読みやすくする。
- 変換は入力と出力の関係が伝わる名前にする。
- 失敗、再試行、検証、保存、送信などの重要な振る舞いは必要に応じて名前に含める。
クラス・型・インターフェース
- 何を表すか、または何の役割を担うかがわかる名詞句にする。
- 実体、値オブジェクト、ポリシー、リポジトリ、クライアント、ファクトリなどの役割語は、既存コードの使い方と揃える。
Base, Common, Abstract, Impl は、公開 API や読み手にとって意味がある場合だけ使う。- インターフェース名は実装都合ではなく、利用側が依存したい能力を表す。
変数・定数
- スコープが広いほど説明的にする。
- 一時変数でも、条件分岐や副作用の判断に使うなら意味が伝わる名前にする。
- 単位、通貨、時刻基準、上限値、状態遷移の向きが重要な値は名前に含める。
- コレクションは要素の種類が伝わる複数形または集合名にする。
ファイル・ディレクトリ
- 中身の責務と公開される概念を一致させる。
- 既存のディレクトリ分類と粒度を優先する。
- ディレクトリ名とファイル名で同じ概念を重複させない。
- 片方に文脈を持たせ、もう片方は短くする。例:
user/repository.go, repository/user.go, auth/token.go
- 汎用的な
helpers, utils, common は、より具体的な責務名にできないか検討する。
進め方
- 対象の名前、周辺コード、責務、呼び出し側を確認する。
- 既存コードの語彙と命名パターンを探す。
- 名前に表すべき情報、周辺コンテキストに任せる情報、隠してよい実装詳細を分ける。
- 第一候補と代替候補を出す。
- 既存名を変える場合は、変更による読みやすさと検索性の改善を説明する。
出力形式
単一の名前を相談された場合:
おすすめは `<name>` です。
理由は <reason> です。
代替案:
- `<alternative A>`: <when it fits>
- `<alternative B>`: <when it fits>
注意点は <pitfall> です。
複数の名前をレビューする場合:
| 現在の名前 | 推奨名 | 理由 |
|---|---|---|
| `<current>` | `<recommended>` | <reason> |
境界
- バグ、仕様違反、セキュリティ、データ整合性のレビューなら
code-review を優先する。
- 実装変更やリネーム作業まで行う場合は
code-general を併用する。
- 次に開発する人の理解しやすさ全体を見る場合は
code-next-developer-review を併用する。
