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

• 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

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) {}

• 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

  )

references/NAMING.md

// 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> { ... }

• 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

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 { ... }
}

• 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

• 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;
}

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

• 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)

• 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) { ... }

• 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)