I keep tripping over

"Every so often I open a PR and see something like this: deployFeature(flag, true, false, true); I run into it more often than I'd like. Not because it's complicated. Just because I have no idea what I'm looking at. So I click into the function definition, scroll a bit, lose my place, jump back, re-read the line...and only then does it click. Tiny interruption. Still annoying every time. I'm not reading code anymore, I'm decoding it"

"Here's a simpler one: createUser(user, true, false); What does that mean? Is the user an admin? Are we sending a welcome email, or skipping validation? I don't know. And at that point I'm not really reading code anymore, I'm decoding it. There's a name for this ("flag arguments," sometimes "boolean blindness"), but honestly I don't really need the term to feel the problem."

"I've definitely written this before: createUser(user, true, false); // isAdmin, sendWelcomeEmail Which kind of gives the whole thing away. If the function call needs a comment to explain the arguments, the API's probably working against me. Why this feels fine at the time Because when I'm writing the function, it feels perfectly reasonable: function createUser(user, isAdmin, sendWelcomeEmail) { // ... } No extra objects. No extra structure, just pass the values in and move on."

"What I use now Most of the time, I just use an object instead: createUser(user, { isAdmin: true, sendWelcomeEmail: false, }); Now I can actually tell what's happening without jumping back to the function definition. And it scales pretty naturally: createUser(user, { isAdmin: true, sendWelcomeEmail: false, skipValidation: true, }); Try stretching positional booleans that far without things getting awkward. Sometimes the boolean is hid"

Positional boolean arguments in function calls obscure meaning and require readers to jump to function definitions to map each true/false value to its purpose. This creates repeated small interruptions and shifts reading from understanding code to decoding it. When a call site needs comments to explain which boolean represents what, the API design is likely working against readability. While passing booleans positionally can feel reasonable during writing, the cost is paid later by anyone who must interpret the call, including the original author. Using an object with named properties allows the meaning to be read directly at the call site and scales naturally as more options are added.

Read at Allthingssmitty