DIP 1019--Named Arguments Lite--Final Review

[Jonathan M Davis]

On Tuesday, August 27, 2019 12:05:25 PM MDT Yuxuan Shui via Digitalmars-d 
wrote:
> On Tuesday, 27 August 2019 at 17:39:44 UTC, H. S. Teoh wrote:
> > On Tue, Aug 27, 2019 at 05:01:21PM +0000, Yuxuan Shui via
> >
> > Digitalmars-d wrote:
> >> On Monday, 26 August 2019 at 21:48:42 UTC, Jonathan M Davis
> >
> >> wrote:
> > [...]
> >
> >> > The _only_ use case IMHO where they add any real value is
> >> > when you have a long parameter list where most of the
> >> > parameters having default arguments.
> >>
> >> Disagree. Oftentimes having the name clarifies a function, so
> >> the _reader_ doesn't have to read the document to figure out
> >> what a function call does
> >
> > [...]
> >
> > That's exactly Jonathan's point.  The reader *assumes*
> > semantics based on the names of the function and parameters.
>
> Well at this point you might just as well say the reader cannot
> *assume* semantics based on the documentation of the function
> either.

There's a world of difference between assuming that what the documentation
says is correct and assuming that you understand what a function does
correctly based off of its name (and potentially the name of its parameters
if named arguments are used). The name of a function should be
representative of what it does and make it easier to remember what the
function does after you've already read the documentation (the same would be
true of parameters if named arguments are in the language), but ultimately,
anyone using a function needs to read its documentation rather than assuming
what it does based on its name or the name of its arguments. In worse cases,
you do have to actually go read the function's source to know what it does,
but that just means that the documentation was bad or nonexistent, which is
of course undesirable and shouldn't happen (especially in publicly available
libraries). We do all unfortunately sometimes have to deal with such
situations, but regardless, it's not reasonable to assume what a function
does based solely on its name, the name of its parameters, or the names of
its arguments. If that's supposed to be one of the main benefits of named
arguments, then I think that that's a great reason _not_ to have them.

This sort of issue seems to come up at least some of the time when naming
functions or types. Some people seem to think that they should be able to
just think of a name and have it exist and act exactly the way they want
without looking anything up. Similarly, some people tend to think that when
they see a name, they should know exactly what it does based on the name and
how it was used without reading the docs. None of that is reasonable IMHO.
You always need to read the documentation, because it's frequently the case
that a function doesn't work exactly the way you infer that it does, and
unless the person who named the function thinks exactly like you do,
differences in names and behaviors are bound to pop up. Ultimately, good
names help people remember what stuff does (and even help them infer what
things probably do before actually reading the docs), but there is no excuse
for not reading the documentation (beyond it not existing, in which case,
that's on the head of whoever wrote it, and you're potentially going to have
to read the source code to get the information you need, which is a whole
other problem).

- Jonathan M Davis