I have lost count of the times I have read a function call with five positional arguments and had to count the commas backwards to work out which one is the timeout and which is the retry count. The call tells you nothing and the signature only helps if you already know it.
The fix has been in the catalogue since 1999. Fowler's Introduce Parameter Object bundles a recurring group of arguments into a class. Two engineers notice the same fields travelling together, a third caller arrives, the bundle gets a name and a type.
The linter rule gets the attention instead. We set max-params to 3, which is the same ceiling Robert C. Martin gives in Clean Code. The argument moves to how to get under it rather than whether the bundle has a name.
The cap is editorial
Zero is ideal, three is the polyadic ceiling, and past that Martin wants very special justification. That is a claim about reading. The rule is easy to treat as the definition.
The bundle is the name and the type. Once the fields have a name and a type, the call site reads as a sentence and the compiler has something to check. Getting the count down is a side effect.
Numbers are the worst case
Five arguments where three are numbers causes the most trouble. Nothing at the call site distinguishes them, so a transposition compiles cleanly and shows up as wrong behaviour in a retry policy.
A parameter object does not prevent the mistake by itself. It makes the mistake legible, because the field you got wrong has a name at the call site rather than a position.
Where I would not apply it
Maths and crypto borrow their abbreviations from the paper being implemented. The honest name is the one in the paper. Bundling those arguments into a struct can move the reader further from the source, so cite the paper next to the module and leave it.
Ordinary application code is the opposite case. There is no paper. The arguments are decisions rather than data, which is exactly the group that wants a name.
The agent angle
An agent will happily write a call with seven positional arguments because the prompt listed seven things. It has no memory of counting commas, so the bad call propagates into everything written against it.
A parameter object gives the agent a https://prickles.org/tenet/parameter-object/S3
