Code Standards

Code Standards

What production-quality code looks like. Use this as a quality bar for writing and evaluating code.

Core principle: Code is read far more often than it is written. Optimize for the reader.

When to Use

• Evaluating your own code before submitting a PR
• Establishing standards for a codebase or team
• Identifying quality problems in existing code
• Answering "is this good enough?"

When NOT to Use

• Conducting a full code review (use code-review skill)
• Refactoring existing code (use refactoring skill)

Naming Standards

Banned patterns:

• Single-letter variables outside loop indices (i, j, k in loops only)
• Abbreviations that aren't industry-standard (usr, mgr, tmp)
• Generic names: data, info, stuff, helper, util, manager
• Misleading names: a function that does Y but is called doX

Complexity Thresholds

Anti-Pattern Reference

Code Smells to Eliminate

Two Hats Rule

Never mix refactoring and optimization in the same session.

• Hat 1: Refactoring — change structure, NOT behavior. Tests must pass unchanged.
• Hat 2: Optimization — improve performance, NOT structure. Benchmarks required.

When switching hats: commit first, then switch context.

The Worst Offenders

// BANNED: Error silencing
try { doThing(); } catch (e) { /* ignore */ }
// FIX: At minimum, log. At most, handle.

// BANNED: Non-null assertion without justification
const user = getUser()!;
// FIX: const user = getUser() ?? throw new Error('...')

// BANNED: any type
function process(data: any): any { ... }
// FIX: explicit types or generics

// BANNED: Mutable global state
let currentUser = null;  // module-level
// FIX: pass through function parameters or use proper context

// BANNED: Function with side effects and a name implying pure query
function getUserName(id: string): string {
  logger.audit(`Name lookup: ${id}`);  // side effect!
  return db.get(id).name;
}
// FIX: separate concerns or document the side effect

Performance Anti-Patterns

Function Quality Standards

A good function:

• Does one thing — can be described in a single sentence without "and"
• Has a clear name — caller doesn't need to read the body
• Has 4 or fewer parameters — more → use options object
• Handles its error cases explicitly — no silent failures
• Has no unexpected side effects — if it has side effects, name makes it clear

// Bad: does multiple things, unclear, silent failure
function process(d: any, f: boolean) {
  try {
    db.save(d);
    if (f) sendEmail(d.email, 'done');
  } catch {}
}

// Good: single responsibility, clear name, typed, explicit errors
async function saveTaskAndNotify(task: Task, notify: boolean): Promise<void> {
  await taskRepository.save(task);
  if (notify) {
    await emailService.sendTaskCreated(task.assignee.email, task);
  }
}

Error Handling Standards

// Every async function either returns a result or throws a typed error

// Bad: returns null on failure (caller must remember to check)
async function getUser(id: string): Promise<User | null> {
  try { return await db.findUser(id); }
  catch { return null; }
}

// Good: throws on not-found, caller can rely on non-null return
async function getUser(id: string): Promise<User> {
  const user = await db.findUser(id);
  if (!user) throw new NotFoundError(`User ${id} not found`);
  return user;
}

// Bad: catch-all silence
try { await riskyOperation(); } catch (e) { /* ignore */ }

// Good: explicit handling
try {
  await riskyOperation();
} catch (err) {
  if (err instanceof NetworkError) {
    logger.warn('Network error, retrying', { err });
    await retry(riskyOperation);
  } else {
    logger.error('Unexpected error', { err });
    throw err;  // re-throw unknown errors
  }
}

Testing Standards

Every non-trivial function needs tests covering:

describe('calculateTax', () => {
  it('returns 0 for zero subtotal', () => { ... });
  it('applies rate to positive subtotal', () => { ... });
  it('throws for negative subtotal', () => { ... });
  it('handles floating point precision correctly', () => { ... });
});

Common Rationalizations to Reject

Automated Quality Gates (by phase)

Verification Checklist

• All names reveal intent (no abbrevations, no generic names)
• No function longer than 50 lines
• No file longer than 300 lines
• No magic numbers (use named constants)
• No boolean function parameters
• No error silencing (every catch either handles or re-throws)
• No commented-out code
• Every function does one thing
• Parameters ≤ 4 (or options object used)
• Tests cover happy path, empty/null, error conditions