Naming Conventions for AI

The Problem

You ask AI to "update the handler." There are 47 handlers. AI picks the wrong one. Or you have a variable called data and AI has no idea what's in it.

Names are the primary way AI understands your code. Poor names mean poor AI performance. Good names mean AI can often guess your intent without explicit instructions.

The Core Insight

Names should encode domain knowledge and intent, not implementation details.

AI has seen millions of codebases. When you use conventional, semantic names, AI can leverage all that training. When you use cryptic abbreviations, AI is flying blind.

The Naming Hierarchy

Semantic Naming Patterns

Variables: Noun + Context

// Bad: What is 'data'?
const data = await fetch('/users');

// Good: Clear type and source
const userListFromApi = await fetch('/users');

// Even better with types
const users: User[] = await fetch('/users');

Functions: Verb + Object + Qualifiers

// Bad: Vague action
function handle(x) { }

// Good: Clear action, object, qualifiers
function validateUserEmailFormat(email: string): boolean { }
function fetchActiveUsersByDepartment(deptId: string): Promise { }
function calculateOrderTotalWithTax(order: Order): number { }

Booleans: Question Form

// Bad: Is this true or false?
const valid = checkEmail(email);

// Good: Reads as a question
const isEmailValid = checkEmail(email);
const hasAdminAccess = user.role === 'admin';
const canEditDocument = user.permissions.includes('edit');
const shouldRetry = attempts < MAX_RETRIES;

Collections: Plural Nouns

// Bad: Singular for collection
const user = getAll();

// Good: Plural indicates collection
const users = getAll();
const activeUserIds = users.filter(u => u.active).map(u => u.id);
const userById = new Map(users.map(u => [u.id, u]));

Domain Language

Use terms from your business domain, consistently:

// E-commerce domain
class ShoppingCart { }       // Not "Basket" or "Bag"
function checkout() { }      // Not "purchase" or "buy"
const lineItems: LineItem[]; // Not "products" or "items"

// Healthcare domain
class Patient { }            // Not "User" or "Client"
function scheduleAppointment() { }
const medicalRecord: MedicalRecord;

Create a glossary in your CLAUDE.md or ARCHITECTURE.md:

# Domain Glossary
- **Order**: A customer's purchase request
- **LineItem**: Single product in an order
- **SKU**: Stock Keeping Unit - unique product identifier
- **Fulfillment**: Process of shipping an order

Anti-Patterns

1. The Abbreviation Trap

// Bad: What do these mean?
const usrMgr = new UsrMgr();
const cfg = loadCfg();
const btn = document.querySelector('.btn');

// Good: Full words
const userManager = new UserManager();
const config = loadConfig();
const submitButton = document.querySelector('.submit-button');

Exception: Industry-standard abbreviations are fine (URL, HTML, API, ID).

2. The Generic Trap

// Bad: Generic names
function handleData(data) { }
function processItems(items) { }
const result = doThing();

// Good: Specific names
function normalizeUserInput(rawInput) { }
function calculateShippingForItems(cartItems) { }
const validationResult = validateForm();

3. The Hungarian Notation Trap

// Bad: Type in name (redundant with type system)
const strUserName: string = 'John';
const arrUsers: User[] = [];
const objConfig: Config = {};

// Good: Let types be types
const userName: string = 'John';
const users: User[] = [];
const config: Config = {};

4. The Inconsistency Trap

// Bad: Same concept, different names
const user = getUser();
const customer = fetchCustomer();
const client = loadClient();

// Good: Consistent naming
const user = getUser();
const admin = getUser(adminId);
const currentUser = getCurrentUser();

File and Directory Naming

# Bad: Vague or inconsistent
src/
├── utils.ts
├── helpers.ts
├── stuff.ts
├── UserManager.ts
├── productUtils.ts

# Good: Consistent, descriptive
src/
├── users/
│   ├── UserService.ts
│   ├── userValidation.ts
│   └── userTypes.ts
├── products/
│   ├── ProductService.ts
│   ├── productPricing.ts
│   └── productTypes.ts
└── shared/
    ├── dateFormatters.ts
    └── httpClient.ts

Test Naming

Test names should describe behavior, not implementation:

// Bad: Tests the function name
describe('validateEmail', () => {
  it('should work', () => { });
  it('test case 1', () => { });
});

// Good: Tests behavior
describe('Email Validation', () => {
  it('accepts valid email formats', () => { });
  it('rejects emails without @ symbol', () => { });
  it('rejects emails with spaces', () => { });
  it('accepts emails with subdomains', () => { });
});