DIP 1019--Named Arguments Lite--Final Review

[Jonathan M Davis]

On Monday, August 26, 2019 4:18:51 PM MDT Ethan via Digitalmars-d wrote:
> On Monday, 26 August 2019 at 21:48:42 UTC, Jonathan M Davis wrote:
> > I know that some folks like Flag, but in general, I think that
> > it's an unnecessary complication.
>
> I'm all about information at a glance. The more you are able to
> understand a line of code without looking at the surrounding
> lines, the clearer and easier to maintain that code is.
>
> Simple example:
>
> void DoSomething( bool Multithreaded, bool Logging );
>
> Which, when invoked using literals, looks like:
>
> DoSomething( true, false );
>
> Yech. That's where flags comes in handy:
>
> DoSomething( Multithreaded.Yes, Logging.No );
>
> Bam. Far more readable at a glance. Named parameters remove the
> template instantiations from that example:
>
> DoSomething( Multithreaded : true, Logging : false );
>
> At the cost of needing to do a "find and replace in files" when
> upgrading compilers/libraries if a parameter name changes, in
> both cases you have far more readable code.

That particular use of Flag is more valuable than many uses of it, because
you actually have multiple arguments, whereas in most cases, only one Flag
gets used. Ultimately though, unless there are a lot of parameters (which is
usually bad function design), I think that the benifit is minimal.

I get the impression that many people just want to use Flag or named
arguments as an excuse to avoid even reading the function's documentation. I
agree that it's great if what a function call does is obvious at a glance,
but I also think that it's dangerous to assume that you know just by looking
at the function call. If you don't actually read the function's
documentation, then it's easy to end up making bad assumptions about what it
does.

Naming is important and having the function's name be representative of what
it does makes it far easier to remember what it's supposed to do, and it
does help see what code probably does at a glance when you haven't read the
docs yet, but ultimately, you need to read the docs, and when people argue
for named arguments, it frequently seems like they want to be able to just
look at a piece of code and know exactly what it does without ever reading
the docs (heck, many people seem to want that based purely off of how a
function is named, which is part of why there's a ton of bikeshedding over
function names). Once you've actually read the docs and are familiar with
what the functions do, then the names serve to remind you rather than inform
you, and the need to label everything is far less. But for a lot of
arguments, you have the names of the variables being passed anyway, and if
anyone really wants to label what a boolean literal is for, they can always
use a comment in-place.

> Besides. Didn't the DIP here include a mechanism for handling
> parameter renaming and forwarding? And marking parameter name
> sets as deprecated?

That doesn't change the fact that the parameter names are then part of the
API and are yet another set of names that are going to be the subject of
bikeshedding and are going to be something that you then can't simply change
without worrying about breaking code. Having a way to deprecate names makes
it possible to change stuff over time, but it's still far better IMHO to not
have the names be part of the API in the first place.

For me personally, I think that having to deal with parameters becoming part
of the API and how that adds to the difficulties that already exist around
naming functions and types in public APIs is enough of a problem that it
outweighs any of the supposed benefits that named arguments provide - even
more so when it frequently seems like the reasons behind wanting named
arguments relate to making badly designed functions easier to deal with
(e.g. having tons of parameters for a function) or relate to folks looking
to avoid reading documentation.

- Jonathan M Davis