common-naming-conventions

common-naming-conventions

すべてのコード成果物に一貫性があり、意図が伝わる命名規則を適用し、コードベースを読みやすく、検索しやすく、自己文書化された状態に保ちます。

使用するタイミング

次の場合にこのスキルを使用します。

• コード（変数、関数、クラス、インターフェース、ファイル、ディレクトリ）を作成または変更するとき
• データベーススキーマ、API エンドポイント、設定キーを作成するとき
• テストファイル、テストケース、テストフィクスチャに名前を付けるとき
• 環境変数、定数、機能フラグを定義するとき
• コードをレビューしていて、一貫性のない名前や分かりにくい名前に気付いたとき

手順

1. 英語を使用する

すべてのコード、変数名、コメント、ドキュメント、コミットメッセージ、ブランチ名は英語で記述する必要があります。例外はありません。

2. 説明的にする — 簡潔さより分かりやすさを優先する

名前の長さは気にしないでください。短くて意味が分かりにくい名前より、長くても説明的な名前のほうが適しています。長くても説明的なコメントより、長くても説明的な名前のほうが適しています。

1. 名前から、何を保持するのか、何をするのか、何を表すのかが分かるようにします。
   • 悪い例：d、tmp、data、result、info、val、item
   • 良い例：elapsedDays、parsedResponse、activeUsers、validationResult
2. data、temp、obj、value、stuff など、意味のない修飾語は避けてください。これらを付け加えたくなる場合は、名前が十分に具体的ではありません。

3. 一貫性を保つ

1つの概念には1つの名前を使用してください。複数の意味に解釈できる名前は使わないでください。技術チーム以外（マーケティング、経営、プロダクト）も含め、チーム全体で命名を統一してください。プロジェクトに辞書やユビキタス言語がある場合は、それに従ってください。

• 同じ操作には、get、fetch、retrieve のいずれか1つを選び、すべてを使わないでください。
• create、add、insert のいずれか1つを選び、相互に置き換えて使わないでください。
• 同じエンティティに対して、user、account、person を使い分けないでください。

4. 常に肯定形にする

否定形のブール値名は使わないでください。否定形は二重否定を頭の中で補正する必要があり、認知負荷を高めます。

• 悪い例：notEditable、disabled、isNotValid、noResults
• 良い例：isEditable、isEnabled、isValid、hasResults

5. 省略形を使わない

省略形は、完全な単語よりも一般的に使われている場合を除き、使わないでください。以下の省略形は明示的に使用が許可されています。

• application の場合は app
• arguments の場合は args
• automatic の場合は auto
• identifier の場合は id
• information の場合は info
• initialize の場合は init
• minimum の場合は min
• maximum の場合は max
• parameter(s) の場合は param / params
• property/properties の場合は prop / props
• reference の場合は ref
• user interface の場合は ui
• utility/utilities の場合は util / utils
• よく知られた頭字語：url、http、api、html、css、sql、json

それ以外はすべて省略せず、完全な形で記述してください。cntUsr、mngr、svc、btn、msg のような分かりにくい短縮形は使わないでください。

6. 関数名には動詞を使う

関数名とメソッド名は、実行する動作を表す動詞で始める必要があります。例：do、render、get、format、calculate、send、validate、create、update、delete、find、check、parse、build。

// Bad: does not start with a verb
const valid(value: string): boolean => {}

// Good: starts with a verb
const checkValidity(value: string): boolean => {}

7. クラス、変数、プロパティには名詞を使う

関数以外の名前（クラス、変数、定数、プロパティ）はすべて、名詞または名詞句にする必要があります。これらは動作ではなく、物事を表します。

// Bad: class name is a verb phrase
class CheckValidity {}

// Good: class name is a noun
class FormValidator {}

8. ブール値には接頭辞を使う

ブール値の変数、プロパティ、パラメーターは、オン／オフの状態を示すため、is、has、will、should、can、was のいずれかで始める必要があります。

// Bad: does not include correct prefix
const value = true;
const visible = true;

// Good: includes prefix
const hasValue = true;
const isVisible = true;

9. 大文字・小文字の表記規則

文脈に応じて正しい大文字・小文字のスタイルを適用します。プロジェクトですでに規則が使われている場合は、それに従います。そうでない場合は、次のデフォルトを使用します。

文脈	スタイル	例
ローカル変数	camelCase	userName, totalAmount
関数／メソッド名	camelCase	calculateTotal(), getUserById()
クラス／インターフェース／型名	PascalCase	UserService, PaymentGateway
定数	UPPER_SNAKE_CASE	MAX_RETRY_COUNT, DEFAULT_TIMEOUT_MS
列挙型メンバー	UPPER_SNAKE_CASE または PascalCase（プロジェクトに合わせる）	ORDER_STATUS_PENDING
環境変数	UPPER_SNAKE_CASE	DATABASE_URL, API_SECRET_KEY
CSS クラス	kebab-case（または BEM）	nav-item, btn--primary
データベースのテーブル	snake_case、複数形	order_items, user_accounts
データベースのカラム	snake_case	created_at, first_name
URL パス／API エンドポイント	kebab-case、リソースには複数形の名詞を使用	/api/user-accounts

10. ファイルとフォルダー

1. kebab-case を使用します。 すべてのファイル名とフォルダー名には、小文字の kebab-case を使用します。大文字と小文字を区別するシステムと区別しないシステムがあるため、ファイル名に大文字を使わないでください。

2. 1 つの概念に関する複数のファイルが含まれる場合は、単数形のフォルダー名を使用します（例：ヘルパーを含むコンポーネント）。text-input/ のようにします。

3. 同じ種類の複数のファイルが含まれる場合は、複数形のフォルダー名を使用します。 text-inputs/、validators/ のようにします。

4. 単一の種類の概念を含むファイルでは、ドット区切りでファイルの種類を名前に含めます。

   // Bad: uses camelCase, no type
   customInput.ts
   
   // Good: uses kebab-case and includes type
   custom-input.class.ts
   custom-input.component.ts
   custom-input.service.ts
   custom-input.spec.ts
   

11. コレクションと数

1. コレクションには複数形の名詞を使用します。users、orderItems、activeConnections のようにします。

   • 型を名前に含めないでください。userList、orderItemArray のような名前は避けます。

2. 数や測定値には単位または概念を含めます。retryCount、timeoutMs、maxWidthPx のようにします。

   • count、timeout、max のような単独の名前は避けます。

12. インターフェースと実装

1. プロジェクトですでに一貫して使用されている場合を除き、インターフェースに I を付けないでください。 インターフェース名には、その能力を表す名前を付けます。Logger、PaymentGateway、UserRepository のようにします。

2. 実装には、アダプター名やストラテジー名を含めてもかまいません。ConsoleLogger、StripePaymentGateway、PostgresUserRepository のようにします。

13. API とデータベースの命名

1. REST エンドポイントのコレクションには複数形の名詞を使用します。

   • GET /api/orders — 一覧
   • GET /api/orders/{orderId} — 単一項目
   • POST /api/orders — 作成
   • URL に動詞を使用しないでください。/api/getOrders、/api/createOrder のようなパスは避けます。

2. 外部キーは、関連するテーブル名を単数形にし、_id を付けます。user_id、order_id のようにします。

3. タイムスタンプには過去分詞を使用します。created_at、updated_at、deleted_at のようにします。

4. ブール型カラムには is_／has_ の接頭辞を使用します。is_active、has_verified_email のようにします。

14. 命名の判断プロセス

名前を付けるときは、次の手順に従います。

1. これは何ですか？ エンティティ、アクション、プロパティ、コレクション、フラグのいずれかを特定します。
2. この文脈で必要な大文字・小文字のスタイルは何ですか？ セクション 9 の表に従って適用します。
3. このコードベースで、同じ概念に対して既存の名前と一貫していますか？ パターンがある場合は、それに従います。
4. 肯定形ですか？ ブール値の場合は、肯定的な接頭辞を使用していることを確認します。
5. 新しいチームメンバーが追加の文脈なしにこの名前を理解できますか？ できない場合は、より明確な名前を選びます。
6. 省略せずに表記されていますか？ 使用が認められていない略語が使われていないことを確認します。

避けるべきアンチパターン

• 単一文字の変数（簡単なループ以外）。配列の反復処理における i、j は問題ありませんが、ユーザーを表す u は避けてください。
• ハンガリアン記法 — 名前に型を含めること：strName、arrItems、bIsActive。型は型システムで表現してください。
• 意味のない接頭辞（my、the、a など）：myService、theUser、aResult。
• 複数形の不統一 — ユーザーの配列を格納する変数の名前が user だったり、単一の注文を格納する変数の名前が orders だったりすること。
• コピー＆ペーストによる命名 — handleClick1、handleClick2。名前に数値の接尾辞が必要なら、抽象化が適切ではありません。
• ファイル名の大文字 — ファイルとフォルダーには、常に小文字のケバブケースを使用してください。

参考資料

• XIP の命名規則