Compact Guard Clauses

Compact Guard Clauses (Early-Return Pattern)

Overview

Default AI code generation often falls into the "Pyramid of Doom" anti-pattern: nesting execution logic 4 to 6 levels deep inside cascading if/else checks ("if user exists $\rightarrow$ if authorized $\rightarrow$ if has active plan $\rightarrow$ if payment valid...").

Deeply nested code increases cyclomatic complexity, wastes 2 to 6 tokens per line on leading indentation whitespace, and creates cognitive fatigue during subsequent code reviews and diff patching.

The Compact Guard Clause Protocol (also known as the Bouncer Pattern) checks for failure conditions at the very top of the function and returns/raises immediately, allowing the primary "happy path" to execute unnested at root indentation.

Nested Pyramid vs. Early-Return Guard Clauses

┌─────────────────────────────────────────────────────────────┐
│                 Indentation & Nesting Impact                │
│                                                             │
│  Nested Pyramid of Doom (Deep Nesting / Token Bloat):       │
│  function processOrder(order) {                             │
│    if (order !== null) {                                    │
│      if (order.isValid) {                                   │
│        if (order.items.length > 0) {                        │
│          // 25 lines indented 8 spaces deep...              │
│          return executeCheckout(order);                     │
│        } else { return { err: "Empty items" }; }            │
│      } else { return { err: "Invalid order" }; }            │
│    } else { return { err: "Null order" }; }                 │
│  }                                                          │
│                                                             │
│  Linear Guard Clauses (Bouncer Pattern - 40% Fewer Tokens): │
│  function processOrder(order) {                             │
│    if (!order) return { err: "Null order" };                │
│    if (!order.isValid) return { err: "Invalid order" };     │
│    if (!order.items.length) return { err: "Empty items" };  │
│                                                             │
│    // Happy path executes flat at root level                │
│    return executeCheckout(order);                           │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘

The 3 Rules of the Bouncer Pattern

1. Invert the Condition to Catch Failures First

Instead of checking for success (if (isSuccess)), check for the negative failure case (if (!isSuccess) return error;).

2. Bail Out Immediately

Never write an else block after an early return, throw, or continue. The rest of the function is implicitly the else branch.

3. Keep the Happy Path at Indentation Level 1

The primary business logic should never be indented beyond 1 tab/2 spaces from the function signature.

Production Multi-Language Examples

TypeScript / JavaScript:

export async function transferFunds(senderId: string, recipientId: string, amount: number) {
  // Guard 1: Input Validation
  if (amount <= 0) throw new ValidationError("Amount must be positive");
  if (senderId === recipientId) throw new ValidationError("Cannot transfer to self");

  // Guard 2: Entity Existence
  const sender = await db.user.findUnique({ where: { id: senderId } });
  if (!sender) throw new NotFoundError("Sender not found");

  // Guard 3: Business Invariant
  if (sender.balance < amount) throw new InsufficientFundsError();

  // Primary Happy Path (Flat, Zero Indentation Bloat)
  return await db.$transaction([
    db.user.update({ where: { id: senderId }, data: { balance: { decrement: amount } } }),
    db.user.update({ where: { id: recipientId }, data: { balance: { increment: amount } } }),
  ]);
}

Python:

def publish_article(article_id: str, author: User) -> Article:
    article = get_article(article_id)
    if not article:
        raise HTTPException(status_code=404, detail="Article not found")
    if article.author_id != author.id and not author.is_admin:
        raise HTTPException(status_code=403, detail="Unauthorized")
    if article.is_published:
        return article  # Idempotent fast return

    # Happy path
    article.is_published = True
    article.published_at = datetime.utcnow()
    return save_article(article)

Benchmark Comparison

Evaluation across 50 generated business logic functions:

Agent Operational Directive

MANDATORY: Code generation agents must structure all validation and precondition logic using early-return guard clauses. Avoid nesting the primary happy path inside multi-level if/else blocks.