Arguments and side effects

Aim for 0–2 arguments; treat 3 as needing a reason and 4+ as a missing concept. Each parameter is something the reader must hold in their head, supply correctly, and keep in the right order. A niladic (zero-arg) or monadic (one-arg) call is trivial to read and to test; a triadic call already forces you to remember which boolean was validate and which was notify. This is not a hard cap — clamp(value, min, max) is a fine, cohesive triad. The heuristic is a smell threshold: at four arguments, ask what concept the call site is reassembling by hand every time.

// 5 positional args: order-dependent, unreadable at the call site
createOrder(customerId, items, 'express', true, null);
//                              ^ shipping  ^ gift  ^ coupon — which is which?

When several parameters always travel together, they are not five inputs — they are one idea (an order request) that has not been named yet.

Collapse a long, related parameter list into a parameter object. When parameters cluster — (x, y, width, height), (street, city, zip, country), the five order fields above — introduce a type that names the cluster. The call site becomes self-documenting because each value is labelled, order stops mattering, and adding a sixth field is a change to the type, not to every call site’s positional list.

interface OrderRequest {
  customerId: string;
  items: LineItem[];
  shipping: ShippingSpeed;
  gift: boolean;
  coupon?: string;
}

createOrder(req: OrderRequest): Order { /* ... */ }

// call site: labelled, order-free, extensible
createOrder({ customerId, items, shipping: 'express', gift: true });

The win is conditional: it only counts when the fields are a genuine concept. Bagging unrelated parameters buys nothing — see the failure inset.

A boolean flag argument almost always means the function does two things — split it. render(item, isAdmin) or save(user, true /* sendEmail */) reads as: the body has an if (flag) that selects between two behaviours. That is two responsibilities sharing one name, and the call site save(user, true) is unreadable without hunting down the parameter. The fix is to make the two behaviours two named functions.

// before: one function, a hidden fork, an opaque call site
function save(user: User, sendEmail: boolean) {
  db.write(user);
  if (sendEmail) mailer.welcome(user);
}
save(user, true);  // true... what is true?

// after: each behaviour named; intent is visible at the call site
function saveUser(user: User) { db.write(user); }
function registerUser(user: User) { saveUser(user); mailer.welcome(user); }
registerUser(user);  // reads as itself

A flag argument is low cohesion made visible in the signature: one function is being asked to be two. Splitting it raises cohesion and makes every call site state which thing it meant.

Don’t return results through arguments — return them. An output argument is a parameter the function mutates so the caller can read the result back out. It inverts the natural reading direction: arguments are supposed to be inputs, so appendFooter(report) looks like it consumes report, when in fact it edits it in place. The reader has to know the body to know who owns the mutation.

// output argument: report goes IN, comes back changed — surprising
function addTotals(report: Report): void {
  report.total = report.lines.reduce((s, l) => s + l.amount, 0);
}

// command–query split: a query returns, a command's effect is in its name
function totalFor(lines: Line[]): number {
  return lines.reduce((s, l) => s + l.amount, 0);
}
const report = { ...draft, total: totalFor(draft.lines) };

If the function computes something, return it. Mutating an argument hides the effect behind a parameter that looked like a plain input.

Make side effects explicit and named; a “pure-looking” function that secretly mutates the world is the costliest lie a signature tells. A name like parseConfig(text) promises a pure transform: text in, config out, no I/O. If it also writes a file or fires a network call, every caller inherits an effect they never asked for — tests need real infrastructure, retries duplicate the write, and reasoning about the program breaks. The rule is command–query separation: a function either answers a question (query, pure, returns a value) or changes the world (command, returns void/effect) — and its name says which.

// LIE: pure-looking name, hidden write
function parseConfig(text: string): Config {
  const cfg = JSON.parse(text);
  fs.writeFileSync('/var/cache/config.json', text); // surprise side effect!
  return cfg;
}

// HONEST: the query is pure; the command names its effect
function parseConfig(text: string): Config { return JSON.parse(text); }
function cacheConfig(text: string): void { fs.writeFileSync('/var/cache/config.json', text); }

The senior reading of all four signals — long lists, flags, output args, hidden effects — is the same: each is a cohesion smell surfacing in the interface. A function with one clear job needs few inputs, no behaviour-selecting flag, no smuggled output, and an effect (if any) that its name admits to.