Domain-Focused Naming

Overview

Names documenting implementation or history create confusion. "NewUserAPI" doesn't tell what it does. "ZodValidator" exposes internals.

Core principle: Names tell what code does in the domain, not how it's built or what it replaced.

Violating the letter of this rule is violating the spirit of naming.

When to Use

Use for:

• Variables, functions, classes, modules
• Refactoring existing code
• Code review feedback
• API design

Use ESPECIALLY when:

• Refactoring (tempted to add "New" or "Improved")
• Replacing implementations (tempted to add "Zod" or "MCP")
• Using design patterns (tempted to add "Factory" or "Manager")
• Documenting changes (tempted to add "Unified" or "Enhanced")

The Rules

NEVER Use Implementation Details

Names expose WHAT, not HOW.

<Bad> ```typescript class ZodValidator { } // Exposes Zod library class MCPToolWrapper { } // Exposes MCP protocol class JSONConfigParser { } // Exposes JSON format ``` </Bad> <Good> ```typescript class Validator { } // What it does class RemoteTool { } // What it represents class ConfigReader { } // What it does ``` </Good>

NEVER Use Temporal Context

Code exists in present. Don't reference past or transitions.

<Bad> ```typescript class NewAPI { } // When does it stop being "new"? class LegacyHandler { } // Calls it legacy but it's running class ImprovedParser { } // Improved from what? class UnifiedService { } // What was unified? class EnhancedValidator { } // Enhanced how? ``` </Bad> <Good> ```typescript class API { } // What it is now class Handler { } // What it does now class Parser { } // What it does now class Service { } // What it is now class Validator { } // What it does now ``` </Good> <Bad> ```typescript class ToolFactory { } // "Factory" adds nothing class ServiceBuilder { } // "Builder" adds nothing class ManagerSingleton { } // "Singleton" adds nothing ``` </Bad> <Good> ```typescript class Tool { } // Clear without pattern class Service { } // Clear without pattern class Registry { } // Clear without pattern </Good> <Bad> ```typescript // During refactoring class NewAuthService { } // References the change class ImprovedValidator { } // References improvement class UnifiedAPIClient { } // References unification ``` </Bad> <Good> ```typescript // During refactoring class AuthService { } // What it is class Validator { } // What it does class APIClient { } // What it is ``` </Good>