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.

NEVER Use Temporal Context

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

NEVER Use Pattern Names (Unless They Add Clarity)

Patterns are implementation details. Most don't help understanding.

// 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()

Quick Reference

When Changing Code

Rule: Never document old behavior or the change in names.

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

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)

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

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)