domain-focused-naming

# 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> ### NEVER Use Pattern Names (Unless They Add Clarity) Patterns are implementation details. Most don't help understanding. <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 // OK when pattern IS the purpose class EventEmitter { } // Observer pattern IS what it does class CommandQueue { } // Queue pattern IS what it does ``` </Good> ### Names Tell Domain Stories Good names form sentences about business logic. <Good> ```typescript // Reads like domain language user.authenticate() order.calculateTotal() payment.process() // Not user.executeAuthenticationStrategy() order.runTotalCalculationAlgorithm() payment.invokeProcessingWorkflow() ``` </Good> ## Quick Reference | Bad Pattern | Why Bad | Good Alternative | |-------------|---------|------------------| | `ZodValidator` | Exposes implementation | `Validator` | | `MCPToolWrapper` | Exposes protocol | `RemoteTool` | | `NewUserAPI` | Temporal reference | `UserAPI` | | `ImprovedParser` | References history | `Parser` | | `ToolFactory` | Pattern name noise | `Tool` or `createTool()` | | `AbstractToolInterface` | Redundant qualifiers | `Tool` | | `executeToolWithValidation()` | Implementation in name | `execute()` | ## When Changing Code **Rule:** Never document old behavior or the change in names. <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> ## Red Flags - STOP and Rename If you catch yourself writing: - "New", "Old", "Legacy", "Improved", "Enhanced" - "Unified", "Refactored", "Updated", "Modern" - Implementation details ("Zod", "JSON", "MCP", "SQL") - Unnecessary pattern names ("Factory", "Builder", "Manager") - Redundant qualifiers ("Abstract", "Base", "Interface") **STOP. Find a name describing actual purpose in the domain.** ## Common Rationalizations | Excuse | Reality | |--------|---------| | "Need to distinguish from old version" | Old version shouldn't exist or should be in different namespace. | | "New developers need to know it's improved" | Code quality shows in behavior, not names. | | "Factory pattern is important here" | If pattern is core purpose, fine. Usually it's not. | | "Everyone knows what Zod is" | Today they do. Names should outlive dependencies. | | "It IS a wrapper around MCP" | That's implementation. What does it DO in your domain? | ## Verification Before committing names: - [ ] Name describes domain purpose - [ ] No implementation details - [ ] No temporal context - [ ] No unnecessary pattern names - [ ] Forms readable sentences with other code - [ ] No "new", "old", "improved", "wrapper" ## Real-World Examples ### Bad Naming (Don't Do This) ```typescript class ImprovedZodConfigValidator { } // ❌ Temporal + implementation const newAPIClientWithRetry = new Client(); // ❌ Temporal + implementation function executeEnhancedToolFactory() { } // ❌ Temporal + pattern noise // Using them const validator = new ImprovedZodConfigValidator(); validator.validateWithNewSchema(); ``` ### Good Naming ```typescript class ConfigValidator { } // ✅ Domain purpose const apiClient = new Client(); // ✅ What it is function createTool() { } // ✅ What it does // Using them - reads like domain language const validator = new ConfigValidator(); validator.validate(); ``` ## Integration with Other Skills **For tactical variable naming:** See skills/naming-variables for comprehensive variable naming techniques (optimal length, scope rules, conventions for booleans/collections/qualifiers, naming as diagnostic tool) **For comment guidelines:** See skills/writing-evergreen-comments for keeping comments evergreen (no temporal context in comments either)