Command–Query Separation (CQS)

Two kinds of method, and only two

Sort every method you write into one of these two boxes. Most methods fall in cleanly, and the type signature usually gives it away.

• Command — it does something. It changes the object's state (adds an item, transfers money, clears a list) and returns nothing (void). Examples: deposit(amount), addItem(item), clear().
• Query — it answers something. It returns a value and changes nothing. You can call it a hundred times in a row and get the same answer (assuming nothing else changed). Examples: getBalance(), isEmpty(), totalItems().

The danger: a query that secretly mutates

The whole reason CQS exists is to stamp out one specific bug: a method that looks like a query — it returns a value, so callers assume it's safe to read — but secretly changes state every time it runs. The two classic offenders:

stack.pop();        // returns the top item AND removes it  ⚠️ both!
idGen.getNextId();  // returns an id AND increments the counter ⚠️ both!

Both look like questions — they hand you back a value — but each one also mutates. That breaks the most useful property of a query: safe repeatability. If getNextId() were a pure query you could call it twice and get the same id. Because it secretly increments, calling it twice gives you 1 then 2. The caller who just wanted to peek at "the next id" has now silently burned an id. A method named like a question that behaves like an order is a landmine.

The fix: split the trap into two honest methods

When you find a method that both answers and acts, split it in two — a pure query that only reads, and a command that only acts. Instead of one popLast() that returns and removes, expose a peekLast() query (read the last item, change nothing) and a removeLast() command (drop the last item, return nothing). Callers compose them when they truly need both:

// BEFORE — one method that both answers and mutates (violates CQS)
const item = cart.popLast();        // returns AND removes

// AFTER — a query and a command, each honest about what it does
const item = cart.peekLast();       // query: read it, cart unchanged
cart.removeLast();                  // command: remove it, returns nothing

Now peekLast() is safe to call in a log line, a debugger, or a retry — it never changes the cart. removeLast() is clearly an action. The caller who wants the old behavior simply calls both, on purpose, in full view. Nothing happens by surprise.

The famous pragmatic exceptions

CQS is a guideline, not a law of physics, and a few well-known methods break it on purpose because the combined operation is genuinely useful and the side effect is expected. stack.pop(), queue.poll(), and iterator.next() all return a value and advance/mutate — and that's fine, because everyone already knows they do, and "take the next one" is one atomic idea. The rule of thumb: it's acceptable to combine when the mutation is the whole point of the call and is obvious from the name. The trap is the accidental mix — a getX() or isReady() that nobody expects to change anything but quietly does.

Apply CQS to almost every method you write

Unlike heavier patterns, CQS is cheap enough to be a default habit. As you write each method, ask: is this an order or a question? Make it clearly one or the other. It pays off most in the places where a hidden side effect would hurt:

• Anything named like a question — get…, is…, has…, count…. Callers, debuggers, and log lines will read these freely, so they must be side-effect-free.
• Code that gets retried or logged — if a value-returning method might run twice (a retry, a console.log, a debugger watch), it must be safe to repeat. CQS guarantees that for queries.
• Domain models and value objects — keeping reads pure makes objects predictable and easy to test: call a query, assert the result, with no setup teardown for surprise mutations.
• APIs other people call — a public method's name is a promise. A query that mutates breaks that promise invisibly, and the bug lands in their code, not yours.