code-naming

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 は、より具体的な責務名にできないか検討する。

進め方

1. 対象の名前、周辺コード、責務、呼び出し側を確認する。
2. 既存コードの語彙と命名パターンを探す。
3. 名前に表すべき情報、周辺コンテキストに任せる情報、隠してよい実装詳細を分ける。
4. 第一候補と代替候補を出す。
5. 既存名を変える場合は、変更による読みやすさと検索性の改善を説明する。

出力形式

単一の名前を相談された場合:

おすすめは `<name>` です。

理由は <reason> です。

代替案:
- `<alternative A>`: <when it fits>
- `<alternative B>`: <when it fits>

注意点は <pitfall> です。

複数の名前をレビューする場合:

| 現在の名前 | 推奨名 | 理由 |
|---|---|---|
| `<current>` | `<recommended>` | <reason> |

境界

• バグ、仕様違反、セキュリティ、データ整合性のレビューなら code-review を優先する。
• 実装変更やリネーム作業まで行う場合は code-general を併用する。
• 次に開発する人の理解しやすさ全体を見る場合は code-next-developer-review を併用する。