Return Modified Value

Removes smells

Symptom

A function that mutates one of its parameters in place; the agent reading the signature can't tell which parameters get mutated without reading the body.

Goal

The function returns the modified value; the agent reads the signature and knows the function is a transformation, not a mutator.

Before the refactoring

function addTax(order) {
  order.total *= 1.1;
}
addTax(order);

After the refactoring

function withTax(order) {
  return { ...order, total: order.total * 1.1 };
}
order = withTax(order);

Example source: Illustrative example written for this site, not a quotation from any source.

Pressure

The agent reasoning about any call must check the function body to identify which parameters mutate; equality, snapshotting, and composition all become guarded.

Tradeoff

Callers must remember to capture the returned value; if any forget they keep the unmodified original, which the agent verifying must check at every call site (or rely on a readonly parameter type).

Relief

Side effects on inputs disappear from the agent's contract reasoning; the function reads as a pure transformation; composition and snapshotting work.

Trap

Forcing return-modified-value on every in-place mutator — including ones where mutation is the contract callers want (performance-critical batch ops) — substitutes one mismatch for another.