DIP 1030--Named Arguments--Community Review Round 1 Discussion

[Paul Backus]

On Wednesday, 12 February 2020 at 05:03:49 UTC, Jonathan M Davis 
wrote:
> If you're familiar with the function, then a naked bool is 
> enough to understand what the function call is doing and no 
> sort of argument name at the call site is necessary. If you 
> aren't familiar with the function, then you should be reading 
> its documentation anyway instead of assuming that you 
> understand what it does based simply on what it's called or 
> what the names of its arguments are.

This strikes me as a false dichotomy, in two ways.

1) It's entirely possible to be familiar enough with a function 
to understand what it does, but not so familiar that you have 
every detail of its parameter list memorized. For example, if I 
see `stdin.byLine(true)`, I may remember that the boolean 
argument has to do with whether it keeps or drops newlines, but 
not be sure which behavior `true` corresponds to. 
`stdin.byLine(keepTerminator: true)` makes it immediately obvious.

2) While function and argument names certainly communicate *less* 
information than documentation does, the amount they communicate 
is not zero. For example, if I'm reading some code in an 
unfamiliar language, and I see something like `Math.abs(x)`, I 
have a pretty good idea what that means even without looking at 
the documentation, because the name refers to an existing piece 
of background knowledge I possess.

Names can't tell you everything, of course. If you need to know 
more, you can (and should) refer to the documentation, or failing 
that, the source code. But sometimes, you don't need to know 
everything, and in those situations, being able to get what you 
need from names is far more convenient than having to search the 
documentation every time.