Clean Code

> Be concise, direct, and solution-focused. Clean code reads like well-written prose — every name reveals intent, every function does one thing, and every abstraction earns its place.

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install clean-code

Core Principles

Naming Rules

Names are the most important documentation. A good name eliminates the need for a comment.

> Rule: If you need a comment to explain a name, rename it.

Naming Anti-Patterns

Function Rules

Guard Clauses

Flatten nested conditionals with early returns. Never nest deeper than 2 levels.

// BAD — 5 levels deep
function processOrder(order: Order) {
  if (order) {
    if (order.items.length > 0) {
      if (order.customer) {
        if (order.customer.isVerified) {
          return submitOrder(order);
        }
      }
    }
  }
  throw new Error('Invalid order');
}

// GOOD — guard clauses flatten the structure
function processOrder(order: Order) {
  if (!order) throw new Error('No order');
  if (!order.items.length) throw new Error('No items');
  if (!order.customer) throw new Error('No customer');
  if (!order.customer.isVerified) throw new Error('Customer not verified');

  return submitOrder(order);
}

Parameter Objects

When a function needs more than 3 arguments, use an options object.

// BAD — too many parameters, order matters
createUser('John', 'Doe', '[email protected]', 'secret', 'admin', 'Engineering');

// GOOD — self-documenting options object
createUser({
  firstName: 'John',
  lastName: 'Doe',
  email: '[email protected]',
  password: 'secret',
  role: 'admin',
  department: 'Engineering',
});

Code Structure Patterns

Composition Over God Functions

// BAD — god function doing everything
async function processOrder(order: Order) {
  // Validate... (15 lines)
  // Calculate totals... (15 lines)
  // Process payment... (10 lines)
  // Send notifications... (10 lines)
  // Update inventory... (10 lines)
  return { success: true };
}

// GOOD — composed of small, focused functions
async function processOrder(order: Order) {
  validateOrder(order);
  const totals = calculateOrderTotals(order);
  const payment = await processPayment(order.customer, totals);
  await sendOrderConfirmation(order, payment);
  await updateInventory(order.items);
  return { success: true, orderId: payment.orderId };
}

Return Type Consistency

Functions should return consistent types. Use discriminated unions for multiple outcomes.

// BAD — returns different types
function getUser(id: string) {
  const user = database.find(id);
  if (!user) return false;     // boolean
  if (user.isDeleted) return null; // null
  return user;                 // User
}

// GOOD — discriminated union
type GetUserResult =
  | { status: 'found'; user: User }
  | { status: 'not_found' }
  | { status: 'deleted' };

function getUser(id: string): GetUserResult {
  const user = database.find(id);
  if (!user) return { status: 'not_found' };
  if (user.isDeleted) return { status: 'deleted' };
  return { status: 'found', user };
}

Anti-Patterns

Pre-Edit Safety Check

Before changing any file, answer these questions to avoid cascading breakage:

File to edit: UserService.ts
├── Who imports this? → UserController.ts, AuthController.ts
├── Do they need changes too? → Check function signatures
└── What tests cover this? → UserService.test.ts

> Rule: Edit the file + all dependent files in the SAME task. Never leave broken imports or missing updates.

Self-Check Before Completing

Before marking any task complete, verify:

NEVER Do

1. NEVER add comments that restate the code — if the code needs a comment to explain what it does, rename things until it doesn't
2. NEVER create abstractions for fewer than 3 use cases — premature abstraction is worse than duplication
3. NEVER leave commented-out code in the codebase — delete it; version control exists for history
4. NEVER write functions longer than 20 lines — extract sub-functions until each does one thing
5. NEVER nest deeper than 2 levels — use guard clauses, early returns, or extract functions
6. NEVER use magic numbers or strings — define named constants with clear semantics
7. NEVER edit a file without checking what depends on it — broken imports and missing updates are the most common source of bugs in multi-file changes
8. NEVER leave a task with failing lint or type checks — fix all errors before marking complete

References

Detailed guides for specific clean code topics: