clean-code

# 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

| Priority | Category | Impact |
| -------- | -------- | ------ |
| 1 | Naming | HIGH — affects every line of code |
| 2 | Functions | HIGH — core unit of abstraction |
| 3 | Code Smells | HIGH — early detection prevents rot |
| 4 | Formatting | MEDIUM — readability at a glance |
| 5 | Error Handling | MEDIUM — robustness and clarity |
| 6 | Comments | MEDIUM — most are avoidable |
| 7 | Object Calisthenics | ASPIRATIONAL — exercises for better OO design |

## 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

```typescript
// 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

```typescript
// 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.

| Smell | Symptom | Quick Fix |
| ----- | ------- | --------- |
| **Long Method** | > 20 lines, multiple concerns | Extract methods |
| **Large Class** | Many responsibilities | Extract class (SRP) |
| **Long Parameter List** | > 3 parameters | Introduce parameter object |
| **Primitive Obsession** | Strings/numbers for domain concepts | Wrap in value objects |
| **Feature Envy** | Method uses another class's data more than its own | Move method |
| **Data Clumps** | Same group of fields appear together | Extract class |
| **Switch Statements** | Type-checking switch/if-else across codebase | Replace with polymorphism |
| **Divergent Change** | One class changed for many reasons | Split by responsibility |
| **Shotgun Surgery** | One change touches many files | Move related code together |
| **Speculative Generality** | "Just in case" abstractions | Delete (YAGNI) |
| **Dead Code** | Unreachable or unused code | Delete |
| **Message Chains** | `a.getB().getC().doSomething()` | Hide delegate (Law of Demeter) |

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.

```typescript
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`

```typescript
// 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

```typescript
// 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.

| # | Rule | Goal |
| - | ---- | ---- |
| 1 | One level of indentation per method | Extract methods aggressively |
| 2 | Don't use `else` | Early returns, guard clauses, polymorphism |
| 3 | Wrap all primitives with domain meaning | Value objects (`Email`, `Money`, `UserId`) |
| 4 | First-class collections | Wrap arrays in domain-specific classes |
| 5 | One dot per line | Law of Demeter — talk to friends only |
| 6 | Don't abbreviate | If the name is too long, the class does too much |
| 7 | Keep entities small | Classes < 50 lines, methods < 10 lines |
| 8 | Limit instance variables | Strive for 2-3; forces focused classes |
| 9 | No getters/setters | Objects have behavior, not just data |

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)