The 4 Rules of Simple Design: A Practical Guide with TypeScript

// ❌ No tests, no confidence
function calculateDiscount(price: number, tier: string): number {
  if (tier === "gold") return price * 0.8;
  if (tier === "silver") return price * 0.9;
  return price;
}

// ✅ Tested behavior — we know exactly what this does
describe("calculateDiscount", () => {
  it("applies 20% discount for gold tier", () => {
    expect(calculateDiscount(100, "gold")).toBe(80);
  });

  it("applies 10% discount for silver tier", () => {
    expect(calculateDiscount(100, "silver")).toBe(90);
  });

  it("applies no discount for unknown tiers", () => {
    expect(calculateDiscount(100, "bronze")).toBe(100);
  });
});

// ❌ What does this do? You have to execute it mentally.
function process(items: { a: number; s: string; d: Date }[]) {
  return items.filter((i) => {
    const n = Date.now();
    const t = i.d.getTime();
    return n - t < 86400000 && i.a > 0 && i.s === "A";
  });
}

// ✅ The code reads like a specification
type OrderItem = {
  amount: number;
  status: "active" | "cancelled" | "pending";
  createdAt: Date;
};

const ONE_DAY_MS = 24 * 60 * 60 * 1000;

function isRecentActiveOrder(order: OrderItem): boolean {
  const age = Date.now() - order.createdAt.getTime();
  return age < ONE_DAY_MS && order.amount > 0 && order.status === "active";
}

function getRecentActiveOrders(orders: OrderItem[]): OrderItem[] {
  return orders.filter(isRecentActiveOrder);
}

// ❌ Too verbose — the names repeat context that's already clear
// file: userService.ts
function getUserByIdFromDatabaseAndReturnUserObject(userId: string): Promise<User> { ... }
function validateUserEmailAddressFormat(emailAddress: string): boolean { ... }
function checkIfUserAccountIsCurrentlyActive(user: User): boolean { ... }
function sendPasswordResetEmailNotificationToUser(user: User): Promise<void> { ... }

// ❌ Too vague — the names tell you nothing
function get(id: string): Promise<unknown> { ... }
function check(s: string): boolean { ... }
function do(u: unknown): Promise<void> { ... }

// ✅ Concise — context is already provided by the module and types
// file: users.ts
function findById(userId: string): Promise<User> { ... }
function isValidEmail(email: string): boolean { ... }
function isActive(user: User): boolean { ... }
function sendPasswordReset(user: User): Promise<void> { ... }

// The caller reads naturally:
import * as users from "./users";
const user = await users.findById(id);
if (users.isActive(user)) { ... }

// ❌ The pricing logic is duplicated across two functions
// invoice.ts

type LineItem = {
  price: number;
  quantity: number;
};

function calculateSubtotal(items: LineItem[]): number {
  let total = 0;
  for (const item of items) {
    total += item.price * item.quantity;
    if (item.quantity >= 10) {
      total -= item.price * item.quantity * 0.1; // bulk discount
    }
  }
  return total;
}

function generatePreview(items: LineItem[]): string {
  let total = 0;
  for (const item of items) {
    total += item.price * item.quantity;
    if (item.quantity >= 10) {
      total -= item.price * item.quantity * 0.1; // bulk discount
    }
  }
  return `Estimated total: $${total.toFixed(2)}`;
}

// ✅ Single source of truth — each concept lives in one place
// pricing.ts

const BULK_THRESHOLD = 10;
const BULK_DISCOUNT_RATE = 0.1;

type LineItem = {
  price: number;
  quantity: number;
};

function lineItemSubtotal(item: LineItem): number {
  const gross = item.price * item.quantity;
  const discount = item.quantity >= BULK_THRESHOLD ? gross * BULK_DISCOUNT_RATE : 0;
  return gross - discount;
}

function calculateSubtotal(items: LineItem[]): number {
  return items.reduce((sum, item) => sum + lineItemSubtotal(item), 0);
}

// invoice.ts
function generatePreview(items: LineItem[]): string {
  return `Estimated total: $${calculateSubtotal(items).toFixed(2)}`;
}

// ❌ Over-engineered for a simple need
type NotificationStrategy = {
  send(message: string, recipient: string): Promise<void>;
};

function createEmailStrategy(): NotificationStrategy {
  return {
    async send(message, recipient) {
      await sendEmail(recipient, message);
    },
  };
}

function createNotificationDispatcher(strategies: Record<string, NotificationStrategy>) {
  return async (type: string, message: string, recipient: string) => {
    const strategy = strategies[type];
    if (!strategy) throw new Error(`Unknown type: ${type}`);
    await strategy.send(message, recipient);
  };
}

const dispatch = createNotificationDispatcher({
  email: createEmailStrategy(),
});

// ✅ Just send the email. Add abstractions when you actually need them.
async function sendNotification(message: string, recipient: string): Promise<void> {
  await sendEmail(recipient, message);
}

// Sometimes duplication is clearer than a forced abstraction
// This is OK — Rule 2 (clarity) beats Rule 3 (DRY)

function formatUserGreeting(user: User): string {
  return `Hello, ${user.firstName} ${user.lastName}!`;
}

function formatAdminGreeting(admin: Admin): string {
  return `Welcome back, ${admin.firstName} ${admin.lastName}. You have ${admin.pendingReviews} pending reviews.`;
}

// ❌ Don't force this into a shared function to eliminate duplication
// The "shared" part (name formatting) is trivial, and the contexts are different

# AI Coding Rules — 4 Rules of Simple Design

You follow Kent Beck's 4 Rules of Simple Design in the order of their priority.
When rules conflict, higher-priority rules always win.

## Rule 1: Passes the Tests (Highest Priority)

- Every function you write or modify MUST have corresponding tests.
- If modifying existing code, run existing tests first. Never break them.
- Write the test BEFORE or alongside the implementation, never as an afterthought.
- Tests must cover: expected behaviour, edge cases, and error paths.
- If you are unsure whether behaviour is correct, ask — do not guess.
- Never mark a task as complete if tests are failing.

## Rule 2: Reveals Intention

- Use descriptive, specific names for variables, functions, types, and modules.
  Bad: `data`, `process`, `handle`, `item`, `tmp`, `val`
  Good: `unpaidInvoices`, `calculateShippingCost`, `OrderStatus`
- But avoid over-descriptive names that repeat context already clear from
  the module, the type signature, or the surrounding code.
  Bad: `getUserByIdFromDatabaseAndReturnUserObject`, `checkIfUserIsActive`
  Good: `findById` (in a users module), `isActive` (takes a User)
- Extract magic numbers and strings into named constants.
- Use TypeScript types to document the shape of data. Prefer `type` over
  `interface` — use `interface` only when declaration merging is needed.
- Prefer named functions over inline lambdas for non-trivial logic.
- Each function should do one thing. If you need "and" to describe it, split it.
- Comments explain WHY, never WHAT. The code itself explains what.

## Rule 3: No Duplication

- Never copy-paste logic. Extract shared behaviour into a function, type, or module.
- Duplication includes: repeated business rules, repeated conditionals,
  repeated data transformations, and repeated structural patterns.
- When you spot duplication, refactor it — even if you didn't introduce it.
- BUT: do not force an abstraction when two pieces of code only look similar
  on the surface but represent different concepts (Rule 2 takes priority).

## Rule 4: Fewest Elements (Lowest Priority)

- Do not create abstractions for hypothetical future requirements.
- Do not introduce unnecessary abstractions, factories, strategies, or wrappers
  unless there is a concrete, current need.
- Prefer functions over classes when no state management is required.
- Prefer module-level functions with namespace imports (`import * as users`)
  over classes with methods. Use types for data shapes, functions for behaviour.
- Remove dead code, unused imports, and unnecessary parameters.
- If an abstraction makes the code harder to follow without reducing real
  duplication, remove it.
- One file with 3 clear functions is better than 3 files with 1 function each,
  unless the functions serve genuinely different domains.

## Conflict Resolution

When rules conflict, apply this priority:
1. Working, tested code (Rule 1) > everything.
2. Clarity (Rule 2) > DRY (Rule 3). A little repetition is OK if the
   alternative is an unclear abstraction.
3. DRY (Rule 3) > Minimalism (Rule 4). An extra function to eliminate
   duplication is justified.
4. Never add complexity to satisfy Rule 4. Minimalism means removing
   unnecessary things, not avoiding necessary ones.

## Refactoring Loop

After every change, mentally run this loop:
1. Are all tests green? → If not, fix.
2. Does the code clearly express intent? → If not, rename/restructure.
3. Is there duplication? → If yes, extract.
4. Can anything be removed without breaking rules 1-3? → If yes, remove.