ALL-PARA0003 · positional_boolean_parameter

Count Boolean parameters a caller must pass by position.

This is a deterministic rule for all languages. Read its implementation.

Definition

Report a parameter typed Boolean that a caller cannot name at the call site. The call then reads render(document, True, False), which says nothing about what is true, and a reader has to open the signature to find out. Worse, the two flags can be transposed and the program keeps compiling, so the mistake surfaces as behavior rather than as an error.

The repair is not always a keyword argument. Two Booleans usually mean the function does two things, and splitting it removes the flags along with the ambiguity.

Evidence

Each finding names the function, the parameter, and its position. The value is the number of positional Boolean parameters.

Exceptions

A parameter a language forces into position, such as the receiver, is not counted. A signature an external contract fixes, like a framework callback, is a reason to exclude the module rather than to fight the interface. A single Boolean whose name reads as a sentence at the call site, such as sorted(values, reverse), is the borderline case this rule deliberately still reports, because the next Boolean added beside it is the one that breaks.

Examples

Bad

def render(document, inline: bool, minified: bool): ...

render(document, True, False)

Good

def render(document, *, inline: bool, minified: bool): ...

render(document, inline=True, minified=False)

The same shape in Rust is `fn render(document: &Document, inline: bool, minified: bool)`, and
the same repair is a small options struct or two functions.

References

• Cites “Refactoring”, remove flag argument. Open reference
• Cites “Clean Code”, chapter 3, flag arguments
• Generalizes Ruff FBT001 boolean-type-hint-positional-argument
• Generalizes Ruff FBT002 boolean-default-value-positional-argument