Clean Code

Principles for transforming "code that works" into "code that is clean" — code that can be read, understood, and enhanced by any developer.

"Code is clean if it can be understood easily — by everyone on the team." — Dave Thomas

When to Apply

Reference these guidelines when:

• Writing new code and choosing names, function signatures, structure
• Reviewing pull requests for readability and maintainability
• Refactoring legacy code or reducing complexity
• Identifying and fixing code smells
• Improving team code standards

Rule Categories

1. Naming

Good names are the single most impactful thing you can do for readability.

Priority order:

1. Consistency — same concept = same name everywhere
2. Intent-revealing — name says what it does, not how
3. Specific — avoid vague names like data, info, manager, handler, utils
4. Searchable — unique enough to grep
5. Brief — short but not cryptic

// Bad
const d = new Date();
const arr = users.filter((u) => u.a);
function process(data: any) {}

// Good
const createdAt = new Date();
const activeUsers = users.filter((user) => user.isActive);
function validatePayment(payment: Payment) {}

Conventions:

• Classes/types: nouns (Customer, OrderRepository). Avoid Manager, Data, Info.
• Methods/functions: verbs (createOrder, validateEmail, isEligible)
• Booleans: question form (isActive, hasPermission, canWithdraw)
• Collections: plural nouns (users, orderItems)

See references/NAMING.md for full guidelines.

2. Functions

// Bad — does too many things, unclear name
function handle(order: Order, sendEmail: boolean, log: boolean) {
  // validate, calculate, save, email, log — all in one
}

// Good — small, single-purpose, descriptive
function validateOrder(order: Order): ValidationResult { ... }
function calculateTotal(items: OrderItem[]): Money { ... }
function saveOrder(order: Order): Promise<void> { ... }

Rules:

• Small — strive for under 20 lines
• Do one thing — if you use "and" to describe it, split it
• One level of abstraction — don't mix business logic with low-level details
• Few arguments — 0-2 ideal, 3+ warrants a parameter object
• No side effects — or name them explicitly (saveAndNotify, not save)
• Command/Query separation — a function either does something or returns something, not both

3. Code Smells

Indicators that code may need refactoring. Not bugs, but design friction.

See references/CODE_SMELLS.md for detailed examples and refactoring strategies.

4. Formatting

The Newspaper Metaphor — code should read top-to-bottom like a newspaper article. High-level summary at the top, details below.

class OrderProcessor {
  // Public API first — the "headline"
  process(order: Order): ProcessResult {
    this.validate(order);
    const total = this.calculateTotal(order);
    return this.save(order, total);
  }

  // Supporting methods below, in order of appearance
  private validate(order: Order) { ... }
  private calculateTotal(order: Order): Money { ... }
  private save(order: Order, total: Money): ProcessResult { ... }
}

Rules:

• Related code stays close together (vertical density)
• Blank lines between concepts (vertical openness)
• Variables declared near their usage
• Caller above callee (stepdown rule)
• Consistent indentation — non-negotiable

5. Error Handling

• Exceptions over error codes — keeps happy path clean
• Don't return null — use undefined, Result types, or throw
• Don't pass null — leads to defensive checks everywhere
• Fail fast — validate at boundaries, trust internals
• Specific exceptions — InsufficientFundsError over generic Error

// Bad — null checks cascade through codebase
function getUser(id: string): User | null {
  return db.find(id);
}
const user = getUser(id);
if (user === null) { ... } // Every caller must check

// Good — throw at boundary, trust within domain
function getUser(id: string): User {
  const user = db.find(id);
  if (!user) throw new UserNotFoundError(id);
  return user;
}

6. Comments

"Don't comment bad code — rewrite it."

Most comments compensate for failure to express intent in code. Prefer self-documenting code over comments.

Good comments:

• Why something is done (business reason, non-obvious decision)
• Warnings ("this is slow because X", "order matters here")
• TODOs with context (link to issue)
• Legal/license headers
• Public API docs (JSDoc for libraries)

Bad comments:

• Restating what the code does (// increment counter)
• Commented-out code (that's what git is for)
• Journal/changelog comments
• Noise (// constructor, // getters)
• Mandated boilerplate

// Bad — restates the obvious
// Check if user is active
if (user.isActive) { ... }

// Good — explains a non-obvious business rule
// Users who haven't verified email within 30 days are auto-deactivated
// per compliance requirement GDPR-2024-42
if (user.isAutoDeactivated) { ... }

7. Object Calisthenics

Nine exercises from Jeff Bay to improve OO design. Treat these as aspirational targets — strict during practice, pragmatic in production.

See references/OBJECT_CALISTHENICS.md for examples of each rule.

Implementation Checklist

Before submitting code:

• Can a new team member understand this without asking questions?
• Are names intention-revealing and consistent?
• Does each function do exactly one thing?
• Are there any code smells I can fix while I'm here?
• Are comments explaining why, not what?
• Is error handling clean and specific?
• Did I leave the code better than I found it? (Boy Scout Rule)