Principle of Least Astonishment

Also Known As

TL;DR

Explanation

The Principle of Least Astonishment (POLA), also called Principle of Least Surprise, states that a component should behave consistently with users' reasonable expectations. In practice: a method named getUser() should never delete a record, a parameter named $count should accept only positive integers, and a function that returns false should not also send an email. Violations create subtle bugs and erode trust in an API. POLA is closely related to Command Query Separation, Tell Don't Ask, and good naming conventions — together they produce APIs that behave predictably.

Common Misconception

Why It Matters

Common Mistakes

• A method named getUser() that also updates a last_seen timestamp — unexpected side effect.
• A constructor that makes HTTP requests or writes to a database.
• Functions that modify their array argument in place in a language where pass-by-value is expected.
• Boolean parameters that invert expected behaviour: delete($id, true) meaning 'soft delete' and delete($id, false) meaning 'hard delete'.

Code Examples

// Method name suggests read, but performs a write
public function getOrder(int $id): Order {
    $order = Order::find($id);
    $order->increment('views'); // side effect — astonishing!
    return $order;
}

// Constructor with side effects — surprises callers
public function __construct() {
    $this->connect(); // unexpected network call
    $this->migrate(); // unexpected DB migration
}

// Name accurately describes behaviour
public function findOrder(int $id): Order {
    return Order::findOrFail($id); // pure read — no surprises
}

public function recordView(int $id): void {
    Order::find($id)->increment('views'); // explicit — callers opt in
}

// Constructor only assigns — side effects via explicit method calls
public function __construct(private readonly DatabaseConfig $config) {}

Tags

Related Terms

References

• https://en.wikipedia.org/wiki/Principle_of_least_astonishment