Boolean Trap

The Boolean Trap is an API design smell where a function accepts a bare boolean argument whose meaning is invisible at the call site. A reader sees setVisible(true) and understands it, but parse(input, true, false) is a riddle: what do the booleans control, and in which order?

The trap deepens as parameters accumulate. createUser(name, true, false, true) is unreadable without opening the function signature, and a single transposed argument silently changes behavior with no compiler complaint.

Why It Happens

Booleans are the easiest way to add a quick flag. A method needs to behave slightly differently in one case, so the author threads a boolean force through it. Each addition seems harmless. Over time several flags pile up, and the call site degrades into a sequence of literal true/false values whose order is meaningful only to someone reading the declaration.

Languages without named arguments (Java, C++, JavaScript) make this worse, because there is no syntactic way to label the value at the call site.

Why It Hurts

Call sites become unreadable and error-prone. Two adjacent boolean parameters of the same type can be swapped with no type error, producing subtle bugs. Booleans also encode only two states, so when a third case appears, teams bolt on a second boolean, creating illegal combinations (e.g. both flags true) that the type system cannot prevent. The API resists extension and obscures intent in code review.

Warning Signs

• Call sites with bare true/false literals whose meaning is not obvious.
• Functions with two or more boolean parameters.
• Comments next to arguments explaining what each boolean means.
• Pairs of booleans that must never both be true.

Better Alternatives

Replace the boolean with a small enumerated type that names each case: parse(input, Mode.STRICT) reads clearly and forbids illegal states. In languages with named/keyword arguments, require them so the call site self-documents. For functions configured many ways, an options object or builder gives every flag a name and a default. Splitting a flag-driven function into two well-named functions (enable() / disable()) is often the simplest fix.

How to Refactor Out of It

Start at the call sites that are hardest to read. Introduce an enum or options type, add it as an overload alongside the boolean version, and migrate callers incrementally. Once all callers use the named form, delete the boolean overload. Where a boolean truly toggles one behavior, consider extracting two intention-revealing methods instead. Add a lint rule (many linters flag boolean literals in calls) to prevent regression, and review new APIs for parameter clarity before merge.