Law of Demeter, tell-don't-ask and CQS

Three rules describe how objects should talk to each other. The Law of Demeter says that a method should send messages only to the objects close to it, not to objects it reaches through them. Tell, don’t ask says that instead of reading another object’s data and deciding for it, you tell that object what to do. Command-query separation (CQS) says that a method either changes state or answers a question, never both. All three keep each piece of behaviour next to the data it needs, so that a change in how one object stores something stays inside that object.

The Law of Demeter: talk to your friends

The law began as a style rule in the Demeter project at Northeastern University, where Ian Holland formulated it in 1987. Karl Lieberherr, Ian Holland and Arthur Riel presented it at the OOPSLA conference in 1988, and Lieberherr and Holland described it again in IEEE Software in 1989. The project’s page states it generally:

Each unit should have only limited knowledge about other units: only units “closely” related to the current unit.

Its short form is “only talk to your immediate friends”. For objects, the project spells out who the friends of a method are. A method may send messages to:

• its parameters, counting the object itself (self) as one;
• the objects it creates;
• the object’s immediate parts: its attributes, what its own methods return, and the elements of a collection it holds;
• for practical reasons, global objects.

Everything reached through a friend is a stranger. In order.customer.wallet.balance, the order is a friend of the code that received it, but the customer is a part of the order, the wallet a part of the customer and the balance a part of the wallet. A caller that writes this chain knows that orders have one customer, that customers have one wallet and that wallets store a number called balance. Each of those facts can change, and each change breaks the caller.

A chain that breaks when the structure changes

A college canteen’s till takes payment for an order. The first version of the model gives every customer one wallet. Two tills use it. pay_by_asking() reaches through the order to the wallet, compares the balance with the total and subtracts it. pay_by_telling() calls order.pay() and leaves the rest to the objects that own the money. Then the canteen gives every student a meal card as well as a top-up wallet, and a payment uses the meal card first. Both tills, run against both versions of the model:

"""Both tills, run against both versions of the model: a 70 order for a customer with enough money."""

import model_v1
import model_v2
from checkout import pay_by_asking, pay_by_telling


def customer(model):
    if model is model_v1:
        return model.Customer("Asha", balance=100)
    return model.Customer("Asha", meal_card=50, top_up=50)


for model in (model_v1, model_v2):
    for till in (pay_by_asking, pay_by_telling):
        order = model.Order(customer(model), prices=[40, 30])
        try:
            result = till(order)
        except AttributeError as error:
            result = f"crashed: {error}"
        print(f"{model.__name__}, {till.__name__}: {result}")

model_v1, pay_by_asking: paid
model_v1, pay_by_telling: paid
model_v2, pay_by_asking: crashed: 'Customer' object has no attribute 'wallet'
model_v2, pay_by_telling: paid

"""Two ways for the till to take payment for an order."""

from errors import InsufficientBalance


def pay_by_asking(order):
    """Reaches through the order and the customer to the wallet, reads its state and decides."""
    wallet = order.customer.wallet
    if wallet.balance < order.total():
        return "declined"
    wallet.balance -= order.total()
    return "paid"


def pay_by_telling(order):
    """Tells the order to pay; the objects that own the money decide how."""
    try:
        order.pay()
    except InsufficientBalance:
        return "declined"
    return "paid"

"""A college canteen's model, first version: every customer has one wallet."""

from errors import InsufficientBalance


class Wallet:
    def __init__(self, balance):
        self.balance = balance

    def debit(self, amount):
        if amount > self.balance:
            raise InsufficientBalance(f"needs {amount}, has {self.balance}")
        self.balance -= amount


class Customer:
    def __init__(self, name, balance):
        self.name = name
        self.wallet = Wallet(balance)

    def pay(self, amount):
        self.wallet.debit(amount)


class Order:
    def __init__(self, customer, prices):
        self.customer = customer
        self.prices = list(prices)

    def total(self):
        return sum(self.prices)

    def pay(self):
        self.customer.pay(self.total())

"""Second version: a customer has a meal card and a top-up wallet, and a payment uses the meal card first."""

from errors import InsufficientBalance


class Wallet:
    def __init__(self, balance):
        self.balance = balance

    def debit(self, amount):
        if amount > self.balance:
            raise InsufficientBalance(f"needs {amount}, has {self.balance}")
        self.balance -= amount


class Customer:
    def __init__(self, name, meal_card, top_up):
        self.name = name
        self.wallets = [Wallet(meal_card), Wallet(top_up)]  # the order in which a payment uses them

    def pay(self, amount):
        if amount > sum(wallet.balance for wallet in self.wallets):
            raise InsufficientBalance(f"needs {amount}")
        for wallet in self.wallets:
            part = min(amount, wallet.balance)
            wallet.debit(part)
            amount -= part


class Order:
    def __init__(self, customer, prices):
        self.customer = customer
        self.prices = list(prices)

    def total(self):
        return sum(self.prices)

    def pay(self):
        self.customer.pay(self.total())

"""The canteen's payment error, shared by both versions of the model and by the till."""


class InsufficientBalance(Exception):
    pass

The asking till crashes on the new model, because customer.wallet no longer exists. Its failure would have been worse if the model had kept a wallet attribute for the top-up wallet: the till would have quietly ignored the meal card, because the rule “meal card first” lives in Customer.pay() and the asking till has its own copy of an older rule. The telling till needed no change at all. The change to how customers pay was made in one method, by the class that knows how customers hold money.

Tests show the same difference. A test of the asking till needs a fake order that returns a fake customer that returns a fake wallet with a balance, three fakes nested inside each other. A test of the telling till needs one fake order with a pay() method.

Tell, don’t ask

The asking till shows the habit that tell-don’t-ask names. It asks the wallet for its balance, decides on the wallet’s behalf and then changes the wallet’s state. Martin Fowler credits the phrase to Andy Hunt and Dave Thomas, and describes it as a reminder of what object orientation is for: data and the behaviour that works on it belong together, so instead of pulling data out of an object and deciding outside it, you tell the object what you want done.

Fowler also warns against reading it as a ban on queries. He writes that he does not use tell-don’t-ask as a rule himself, but tries to put data and behaviour together, which leads to much the same place. He has seen it turn people into “GetterEradicators” who remove every query method, although asking an object for information is often the clearest design. A useful reading: when a caller reads an object’s state in order to change that same object, move the decision into the object. Reading data to show it, print it or pass it on is fine.

Command-query separation

Bertrand Meyer, in Object-Oriented Software Construction, divides methods into two kinds. A command changes the state of an object and returns nothing. A query returns a value and changes nothing that callers can observe. Fowler adds a practical exception: popping a stack both changes it and returns the top element, and he keeps that idiom while following the rule wherever he can. The benefit of the split is that queries are safe: they can be called twice, in any order, from a test or a log line, and the answer does not change because someone asked.

The cost of mixing the two shows up when something fails halfway. A clinic’s waiting room calls patients by token number. The first queue has one method, next_and_announce(), that removes the next token and shows it on the display. The second has a query, peek(), and a command, remove(token). The display fails on its first call, and each caller retries once:

"""The waiting-room display fails once and works the second time. The caller retries once in both designs."""

from token_queues import MixedQueue, SeparatedQueue


class FlakyDisplay:
    def __init__(self):
        self.calls = 0
        self.shown = []

    def announce(self, token):
        self.calls += 1
        if self.calls == 1:
            raise ConnectionError("display did not answer")
        self.shown.append(token)


def call_next_mixed(queue, display):
    for attempt in (1, 2):
        try:
            return queue.next_and_announce(display)
        except ConnectionError:
            continue


def call_next_separated(queue, display):
    for attempt in (1, 2):
        token = queue.peek()
        try:
            display.announce(token)
        except ConnectionError:
            continue
        queue.remove(token)
        return token


for name, queue, call_next in (
    ("mixed", MixedQueue(["T-1", "T-2", "T-3"]), call_next_mixed),
    ("separated", SeparatedQueue(["T-1", "T-2", "T-3"]), call_next_separated),
):
    display = FlakyDisplay()
    call_next(queue, display)
    print(f"{name:10} announced {display.shown}, still waiting {queue.waiting()}")

mixed      announced ['T-2'], still waiting ['T-3']
separated  announced ['T-1'], still waiting ['T-2', 'T-3']

"""A clinic's token queue in two designs: one method that removes and announces, or a query and a command."""

from collections import deque


class MixedQueue:
    def __init__(self, tokens):
        self._tokens = deque(tokens)

    def next_and_announce(self, display):
        """Removes the next token AND announces it: a command and a query in one method."""
        token = self._tokens.popleft()
        display.announce(token)
        return token

    def waiting(self):
        return list(self._tokens)


class SeparatedQueue:
    def __init__(self, tokens):
        self._tokens = deque(tokens)

    def peek(self):
        """A query: which token is next? It changes nothing, so it is safe to ask again."""
        return self._tokens[0]

    def remove(self, token):
        """A command: the token has been called. It returns nothing."""
        if self._tokens[0] != token:
            raise ValueError(f"{token} is not at the front of the queue")
        self._tokens.popleft()

    def waiting(self):
        return list(self._tokens)

With the mixed method, the first attempt removed T-1 before the display failed, so the retry removed and announced T-2, and the patient holding T-1 is never called. With the query and the command, the caller asks which token is next, announces it and removes it only once the announcement worked, so the retry announces T-1. The separated design also makes the order of steps visible in the caller, where the retry policy lives, instead of hiding it inside one method.

What is not a violation

The Law of Demeter is about objects that hide their structure. Code that walks through data whose structure is its public contract is not breaking it, and treating every chain of dots as a fault leads to absurd designs:

• Fluent builders. Query("orders").where(paid=True).order_by("date") talks to one query object at every step, because each method returns a query.
• Values and data structures. point.x, config["db"]["host"] or a data transfer object passed between layers expose their fields on purpose, and so does a chain of string or path operations such as name.strip().lower().
• Your own parts. Inside Room, self.minibar.total() sends a message to an object the room holds, which the law allows.

Forwarding methods have a cost too: every one of them widens the interface of the class that holds it, which the Interface Segregation Principle warns about. The fix for a chain is rarely “add a method that returns the far object”; it is to move the operation, so that the caller asks for what it needs done.

Interview questions

Warm-up (fresher to mid level): what is the Law of Demeter, and what does a violation look like? It is a style rule from Northeastern University’s Demeter project: a method should send messages only to its friends, which are its own object, its parameters, the objects it creates and the objects its object holds directly. Objects reached through those friends are strangers. A violation is a chain such as order.customer.wallet.balance, where the caller depends on how three other classes store their data, so a change to any of them, such as customers getting two wallets, breaks it. The fix is not a getter for each step but moving the behaviour: the caller tells the order to pay, the order tells its customer, and the customer decides which wallet to use. Fluent builders and plain data structures are not violations.

Key takeaways

• The Law of Demeter: a method talks to itself, its parameters, the objects it creates and the objects it holds, not to objects reached through them.
• A chain of calls couples the caller to the structure of every object along it, and needs a nested fake for each step in tests.
• Tell, don’t ask: when a caller reads an object’s state to change that object, move the decision into the object. Queries for showing or passing on data are fine.
• Command-query separation: commands change state and return nothing; queries return data and change nothing. A method that does both makes retries skip or repeat work.
• Builders, values and data structures expose their structure on purpose; move operations, not data, to fix a chain.