Least Astonishment - Learning Module

Loading content...

0/246

Predictable Behavior

The Architecture of Trust

When developers work with code they trust, they move fast. They don't second-guess method calls. They don't write defensive null checks around every operation. They don't add logging statements to verify that things happened. They simply write what they mean and trust the system to do what it says.

Predictable behavior is the foundation of this trust. It's not enough for code to do the right thing—it must do the right thing consistently, reliably, and in a way developers can anticipate.

This page examines the concrete properties and patterns that make behavior predictable. These aren't abstract ideals; they're practical engineering techniques that, when applied systematically, transform code from mysterious to reliable.

What You Will Learn

By the end of this page, you will understand five key properties of predictable behavior: determinism, idempotency, explicit state, clear contracts, and consistent error handling. You'll learn patterns for achieving each and understand why these properties reduce bugs, simplify debugging, and accelerate development.

Determinism: Same Inputs, Same Outputs

Deterministic behavior is the most fundamental form of predictability. A deterministic function always produces the same output given the same input. No randomness, no hidden state, no dependency on external systems that might behave differently.

A function f is deterministic if for all inputs x, f(x) always returns the same value.

Determinism is the gold standard of predictability because it makes code:

Testable — Run the same test 1000 times; get the same result
Debuggable — Reproduce issues by replaying inputs
Cacheable — Same inputs mean cached results are valid
Parallelizable — No hidden dependencies between calls

Pure Functions

Deterministic functions with no side effects are called pure functions. They're the most predictable code possible: call them anywhere, anytime, any number of times, and the only effect is the return value. Functional programming builds entire systems from pure functions for exactly this reason.

Sources of Non-Determinism:

Understanding what breaks determinism helps you avoid or isolate it:

Random Number Generation — Obvious, but subtle when libraries use randomness internally (shuffling algorithms, UUID generation, hash seed randomization).
Current Time/Date — Date.now(), LocalDateTime.now(), or any time-dependent logic. Tests that pass at 11:59 PM and fail at 12:01 AM are a symptom.
External System Dependencies — Network calls, database queries, file system reads. The external system might return different data or fail entirely.
Mutable Shared State — If multiple threads or processes share mutable state, the order of operations affects results. This is the domain of race conditions.
Hash Map Iteration Order — In many languages, hash map iteration order is not guaranteed. Code that depends on order is non-deterministic across runs.
Floating Point Accumulation — Different orderings of floating-point operations can produce different results due to rounding. (a + b) + c may not equal a + (b + c).

non-deterministic.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// ❌ Non-Deterministic
function generateReport(orders: Order[]) {
  const timestamp = new Date();
  const randomId = Math.random();
  
  return {
    id: randomId,
    generatedAt: timestamp,
    summary: summarize(orders),
    // Different every time!
  };
}
 
function summarize(orders: Order[]) {
  // Depends on iteration order
  const byStatus = new Map();
  for (const order of orders) {
    const current = byStatus.get(order.status);
    byStatus.set(order.status, (current ?? 0) + 1);
  }
  // Map iteration order may vary!
  return [...byStatus.entries()];
}

deterministic.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// ✅ Deterministic
function generateReport(
  orders: Order[],
  clock: Clock,      // Injected
  idGenerator: IdGen // Injected
) {
  return {
    id: idGenerator.next(),
    generatedAt: clock.now(),
    summary: summarize(orders),
  };
}
 
function summarize(orders: Order[]) {
  const byStatus = new Map();
  for (const order of orders) {
    const current = byStatus.get(order.status);
    byStatus.set(order.status, (current ?? 0) + 1);
  }
  // Explicitly sort for consistent order
  return [...byStatus.entries()]
    .sort(([a], [b]) => a.localeCompare(b));
}

Dependency Injection for Determinism

The key pattern for achieving determinism is dependency injection. Instead of calling Date.now() directly, accept a Clock parameter. Instead of using Math.random(), accept a RandomSource. In tests, inject deterministic implementations. In production, inject real ones. This separates the logic from its non-deterministic dependencies.

Idempotency: Safe to Repeat

Idempotent operations produce the same result whether executed once or multiple times. This is crucial for distributed systems, retry logic, and anywhere operations might be duplicated.

An operation f is idempotent if f(f(x)) = f(x) for all x.

Or more simply: doing it twice is the same as doing it once.

Why Idempotency Matters:

In the real world, things fail. Networks drop packets. Services time out. Clients retry. If your operations aren't idempotent, retries can cause catastrophic problems:

Charge a customer's credit card twice
Send duplicate emails
Create duplicate records
Apply discounts multiple times

Idempotency in HTTP Methods
Method	Idempotent?	Reasoning
GET	Yes	Reading doesn't change state; can read repeatedly
PUT	Yes	Setting to a specific value is always the same value
DELETE	Yes	Deleting what's already deleted is still deleted
POST	No	Creates new resource; calling twice creates two resources
PATCH	Depends	Relative changes (increment) aren't; absolute (set to X) are

Patterns for Achieving Idempotency:

1. Idempotency Keys

For non-naturally-idempotent operations, use client-generated unique keys. The server stores processed keys and returns cached results for duplicates.

async function processPayment(request: PaymentRequest) {
  const existing = await db.payments.findByIdempotencyKey(request.idempotencyKey);
  if (existing) {
    return existing.result; // Return cached result
  }
  
  const result = await chargeCard(request);
  await db.payments.save({
    idempotencyKey: request.idempotencyKey,
    result,
  });
  return result;
}

2. Absolute Rather Than Relative Updates

// ❌ Not idempotent: incrementing twice increases by 2
await db.user.update({ balance: { increment: 100 } });

// ✅ Idempotent: setting to specific value is always that value
const newBalance = currentBalance + 100;
await db.user.update({ balance: newBalance });

3. Conditional Operations

// ❌ Not idempotent: always sets
await db.user.update({ status: 'active' });

// ✅ Idempotent: only sets if condition met
await db.user.updateWhere(
  { status: 'pending' },   // Only if currently pending
  { status: 'active' }
);

The Retry Trap

Non-idempotent operations with automatic retries are a disaster waiting to happen. If your HTTP client retries failed POST requests, and your server doesn't handle duplicates, you will create duplicate data. Either make operations idempotent or disable retries—never assume the network is reliable.

Explicit State: No Hidden Surprises

One of the most common sources of unpredictable behavior is hidden state—state that affects behavior but isn't visible to the caller. When state is implicit, developers must know about it to use the system correctly. When it's explicit, the code enforces correct usage.

The Problem with Implicit State:

Consider a connection pool that implicitly tracks whether connections are 'in use':

implicit-state.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// ❌ Implicit state: caller must remember to release
class ConnectionPool {
  private connections: Connection[] = [];
  private inUse: Set<Connection> = new Set();
  
  acquire(): Connection {
    const conn = this.connections.find(c => !this.inUse.has(c));
    if (!conn) throw new Error('Pool exhausted');
    this.inUse.add(conn);
    return conn;  // Caller must remember to release!
  }
  
  release(conn: Connection): void {
    this.inUse.delete(conn);
  }
}
 
// Calling code - easy to forget release!
const conn = pool.acquire();
const result = await conn.query(sql);
// Forgot pool.release(conn) - connection leaked!

Making State Explicit:

Explicit state makes constraints visible and enforceable. Here are patterns for explicitness:

explicit-state.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// ✅ Explicit state: structure enforces correct usage
class ConnectionPool {
  async withConnection<T>(fn: (conn: Connection) => Promise<T>): Promise<T> {
    const conn = await this.acquire();
    try {
      return await fn(conn);
    } finally {
      this.release(conn);  // Automatic release!
    }
  }
}
 
// Calling code - impossible to forget release
await pool.withConnection(async (conn) => {
  return await conn.query(sql);
});  // Connection released automatically
 
// ✅ Alternative: RAII with Symbol.dispose (TypeScript 5.2+)
async function doWork() {
  using conn = await pool.acquire();  // Disposed at scope end
  return await conn.query(sql);
}

Patterns for Explicit State

•Required Parameters — If state is needed, require it as a parameter. Don't rely on implicit initialization.
•State Machines — Model valid states and transitions explicitly. Invalid transitions become compilation errors or clear runtime errors.
•RAII / Using Statements — Tie resource lifecycle to scope. Acquisition and release happen together.
•Factory Functions — Return fully-initialized objects. Don't allow partially-constructed objects to exist.
•Immutable Transitions — Instead of mutating state, return new objects representing the new state.
•Builder Pattern — Accumulate configuration explicitly, then validate and build atomically.

Type-Driven Explicit State

Use your type system to make invalid states unrepresentable. If a 'Submitted' order must have a submission timestamp, ensure the Submitted type includes that timestamp. The type system then prevents creating submitted orders without timestamps—no documentation or discipline required.

Clear Contracts: Promises You Can Count On

A contract defines what a piece of code promises to do and what it requires in return. Clear contracts make behavior predictable because developers know exactly what to expect.

The Components of a Contract:

Preconditions — What must be true before calling. If violated, the caller has made an error.
Postconditions — What will be true after calling. This is the caller's guarantee.
Invariants — What remains constant throughout. These must hold before and after every public operation.

contracts.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
/**
 * Transfers funds between accounts.
 * 
 * @precondition fromAccount and toAccount are valid, active accounts
 * @precondition amount > 0
 * @precondition fromAccount.balance >= amount
 * @precondition fromAccount !== toAccount
 * 
 * @postcondition fromAccount.balance decreased by amount
 * @postcondition toAccount.balance increased by amount
 * @postcondition transfer is recorded in audit log
 * @postcondition no other account balances changed
 * 
 * @throws InsufficientFundsError if balance < amount (despite precondition)
 * @throws AccountFrozenError if either account becomes frozen during transfer
 */
function transfer(fromAccount: Account, toAccount: Account, amount: Money): void {
  // Validate preconditions at runtime for safety
  if (amount.value <= 0) {
    throw new InvalidArgumentError('Amount must be positive');
  }
  if (fromAccount.id === toAccount.id) {
    throw new InvalidArgumentError('Cannot transfer to same account');
  }
  if (!fromAccount.isActive || !toAccount.isActive) {
    throw new AccountInactiveError();
  }
  
  // Invariant: total money in system remains constant
  const totalBefore = fromAccount.balance.add(toAccount.balance);
  
  try {
    fromAccount.debit(amount);
    toAccount.credit(amount);
  } finally {
    // Verify invariant maintained
    const totalAfter = fromAccount.balance.add(toAccount.balance);
    assert(totalBefore.equals(totalAfter), 'Money invariant violated');
  }
  
  auditLog.record(new TransferEvent(fromAccount, toAccount, amount));
}

Levels of Contract Enforcement:

Documentation-Only Contracts (Weakest)

Contracts stated in comments/docs only
Relies on developers reading and following
Violations discovered at runtime or never

Runtime-Checked Contracts (Moderate)

Assert/validate preconditions at start
Check postconditions before return
Violations become clear errors

Type-Enforced Contracts (Strongest)

Use types to make violations impossible
Invalid calls don't compile
Zero runtime overhead for checking

Weak Contract

•// @param age - must be positive
•function setAge(age: number) { ... }
•
•setAge(-5) // Compiles! Fails at ???

Strong Contract

•type PositiveNumber = number & { readonly brand: unique symbol }
•function setAge(age: PositiveNumber) { ... }
•
•setAge(-5) // Compile error!

Design by Contract

The idea of contracts as first-class design elements comes from Bertrand Meyer's 'Design by Contract' methodology. Languages like Eiffel have built-in contract support. In other languages, you can use assertion libraries, type brands, or runtime validation libraries to achieve similar benefits.

Consistent Error Handling

Few things destroy predictability faster than inconsistent error handling. When some methods throw, others return null, and still others return Result objects, developers never know what to expect.

The Error Handling Spectrum:

Approach	Signal	When to Use
Exceptions	Throw	Truly exceptional conditions; caller can't reasonably prevent
Null/Undefined	Return null	Expected absence; 'not found' scenarios
Result Types	Return Result<T, E>	Recoverable failures; domain errors
Error Callbacks	Invoke callback	Async operations (older style)
Status Codes	Return code	APIs, system interfaces

The Key Principle: Choose One, Apply Everywhere

Consistency matters more than which approach you choose. If your codebase uses Result types, use them everywhere. If it uses exceptions for recoverable errors, use exceptions everywhere. Mixing approaches creates confusion.

Patterns for Consistent Error Handling:

error-handling.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// ✅ Pattern: Result Types for Domain Errors
type Result<T, E> = 
  | { success: true; value: T }
  | { success: false; error: E };
 
class UserService {
  findById(id: UserId): Result<User, 'not_found' | 'database_error'> {
    // Consistent: always returns Result, never throws
  }
  
  create(data: CreateUserData): Result<User, 'validation_error' | 'duplicate_email'> {
    // Same pattern: Result for all domain operations
  }
  
  delete(id: UserId): Result<void, 'not_found' | 'has_dependencies'> {
    // Even for void, use Result for consistency
  }
}
 
// Calling code knows exactly what to expect
const result = userService.findById(userId);
if (result.success) {
  console.log(result.value.name);
} else {
  // TypeScript knows error is 'not_found' | 'database_error'
  switch (result.error) {
    case 'not_found': return showNotFoundPage();
    case 'database_error': return showErrorPage();
  }
}

Error Handling Consistency Checklist

•Document the approach — State explicitly which approach the codebase uses and when
•Use types to enforce — If using Result types, make the return type explicit; callers can't ignore it
•Handle at appropriate level — Don't catch and re-throw repeatedly; handle once at the right layer
•Preserve information — Include context, causes, and actionable messages in errors
•Fail fast for bugs — Programmer errors (null pointers, out-of-bounds) should crash immediately, not return error codes
•Distinguish expected vs unexpected — 'User not found' is expected; 'database connection lost' is unexpected

The Silent Failure Trap

The worst form of inconsistency is silent failure—when operations fail but don't signal it at all. Returning null when something went wrong (not when absence is expected), catching and ignoring exceptions, or setting a boolean flag that no one checks. These create impossible-to-debug systems where errors propagate silently until they surface far from the cause.

Stability and Backward Compatibility

Predictability extends across time. Code that behaves one way today and differently tomorrow is surprising, even if both behaviors are individually correct. Stability means behavior remains consistent across versions.

Semantic Versioning and Behavior:

Semantic versioning (SemVer) is built on this principle:

Patch (1.0.X) — Bug fixes only; behavior unchanged for correct usage
Minor (1.X.0) — New features; existing behavior unchanged
Major (X.0.0) — Breaking changes; behavior may change

The implicit promise: if you depend on version 1.2.3, upgrading to 1.2.4 or 1.3.0 won't break your code. Only 2.0.0 might.

Patterns for Stable Evolution:

1. Deprecation Before Removal

/** @deprecated Use specificSearch() instead. Will be removed in v3.0. */
function search(query: string): Result[] {
  console.warn('search() is deprecated; use specificSearch()');
  return specificSearch({ query, limit: 100 });
}

2. Feature Flags for Gradual Migration

function processOrder(order: Order) {
  if (featureFlags.useNewOrderFlow) {
    return newOrderProcessor.process(order);
  }
  return legacyOrderProcessor.process(order);
}

3. Versioned APIs

// Old clients continue working; new clients use v2
app.post('/api/v1/users', v1UserController.create);
app.post('/api/v2/users', v2UserController.create);

4. Extension Points for Future Needs

interface Config {
  required: string;
  optional?: string;
  // Reserved for future use; allows adding fields without version bump
  [key: string]: unknown;
}

Hyrum's Law

"With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody." —Hyrum Wright. This means even 'undefined behavior' becomes a de facto contract. Be very careful about what your code does, even incidentally.

Testing for Predictability

Predictability should be verified, not assumed. Specific testing techniques help ensure behavior remains predictable:

Testing Techniques for Predictability

•Determinism Tests — Run the same test multiple times; verify identical results. Use test runners that randomize test order to expose hidden state dependencies.
•Idempotency Tests — Call the same operation multiple times; verify the result is identical to calling once. Test with 2, 3, and large numbers of repetitions.
•Contract Tests — Verify preconditions, postconditions, and invariants. Use property-based testing to generate many inputs and verify contracts hold.
•Chaos Engineering — Inject failures (network errors, timeouts, disk failures) and verify the system still behaves predictably.
•Regression Tests — Capture current behavior; verify it doesn't change unexpectedly. Snapshot testing is useful here.
•Boundary Tests — Test at edges: empty inputs, maximum values, null values. Edge cases often reveal unexpected behavior.

predictability-tests.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
describe('TransferService', () => {
  // Determinism test
  it('produces same result with same inputs', () => {
    const result1 = service.calculate(input);
    const result2 = service.calculate(input);
    expect(result1).toEqual(result2);
  });
  
  // Idempotency test
  it('is idempotent for status updates', async () => {
    await service.markComplete(orderId);
    const afterFirst = await service.getOrder(orderId);
    
    await service.markComplete(orderId);
    const afterSecond = await service.getOrder(orderId);
    
    expect(afterFirst).toEqual(afterSecond);
  });
  
  // Contract test
  it('maintains money invariant during transfer', async () => {
    const totalBefore = accountA.balance + accountB.balance;
    
    await service.transfer(accountA, accountB, amount);
    
    const totalAfter = accountA.balance + accountB.balance;
    expect(totalAfter).toEqual(totalBefore);
  });
  
  // Property-based contract test
  it('never leaves system in invalid state', () => {
    fc.assert(fc.property(
      fc.array(fc.oneof(
        fc.record({ type: fc.constant('deposit'), amount: fc.nat() }),
        fc.record({ type: fc.constant('withdraw'), amount: fc.nat() }),
      )),
      (operations) => {
        applyOperations(account, operations);
        return account.balance >= 0;  // Invariant: balance never negative
      }
    ));
  });
});

Summary: Predictable Behavior

We've explored the concrete properties and patterns that make software behavior predictable. Let's consolidate these insights:

Key Takeaways

•Determinism is foundational — Same inputs produce same outputs. Inject dependencies to isolate non-deterministic elements.
•Idempotency enables reliability — Operations safe to repeat enable robust retry logic. Use idempotency keys, absolute updates, and conditional operations.
•Explicit state prevents confusion — Make state visible and enforceable. Use RAII patterns, required parameters, and state machines.
•Clear contracts set expectations — Define preconditions, postconditions, and invariants. Enforce them with types when possible, runtime checks when not.
•Consistent error handling builds trust — Choose one approach and apply everywhere. Make error paths explicit and typed.
•Stability extends predictability through time — Deprecate before removing. Version APIs. Respect backward compatibility.
•Test predictability explicitly — Determinism, idempotency, contracts, and regressions all need verification.

What's next:

Predictability starts with behavior but extends to naming. The next page explores how naming choices affect the Principle of Least Astonishment—how method names set expectations, how inconsistent naming creates confusion, and how to develop a naming sense that makes code self-documenting.

Page Complete

You now understand the properties that make behavior predictable: determinism, idempotency, explicit state, clear contracts, consistent error handling, and stability. These aren't just nice-to-haves—they're the engineering techniques that separate reliable systems from fragile ones. Next, we'll examine how naming amplifies or undermines predictability.