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

[Manu]

On Mon, Feb 10, 2020 at 4:05 PM Jonathan Marler via Digitalmars-d
<digitalmars-d at puremagic.com> wrote:
>
> On Monday, 10 February 2020 at 23:20:34 UTC, Jonathan Marler
> wrote:
> > On Thursday, 6 February 2020 at 06:08:59 UTC, Mike Parker wrote:
> >> This is the feedback thread for the first round of Community
> >> Review for DIP 1030, "Named Arguments":
> >>
> >> https://github.com/dlang/DIPs/blob/44b0d4ec0da6a2e797ede748fb1e81cd6db10371/DIPs/DIP1030.md
> >>
> >> Here in the discussion thread, you are free to discuss
> >> anything and everything related to the DIP. Express your
> >> support or opposition, debate alternatives, argue the
> >> merits... in other words, business as usual.
> >>
> >> However, if you have any specific feedback for how to improve
> >> the the proposal itself, then please post it in the feedback
> >> thread. The feedback thread will be the source for the review
> >> summary I write at the end of this review round. I will post a
> >> link to that thread immediately following this post. Just be
> >> sure to read and understand the Reviewer Guidelines before
> >> posting there:
> >>
> >> https://github.com/dlang/DIPs/blob/master/docs/guidelines-reviewers.md
> >>
> >> The review period will end at 11:59 PM ET on February 20, or
> >> when I make a post declaring it complete. Discussion in this
> >> thread may continue beyond that point.
> >>
> >> At the end of Round 1, if further review is deemed necessary,
> >> the DIP will be scheduled for another round of Community
> >> Review. Otherwise, it will be queued for the Final Review and
> >> Formal Assessment.
> >>
> >> Please stay on topic here. I will delete posts that are
> >> completely off topic.
> >
> > I'm curious what the current state of druntime/phobos is with
> > parameter name consistency.
> >  I took a quick look at std.math in phobos to see what some of
> > the current argument names are:
> >
> > auto conj(Num)(Num z) @safe pure nothrow @nogc
> > auto abs(Num)(Num x) @nogc pure nothrow
> > real cos(real x) @safe pure nothrow @nogc { pragma(inline,
> > true); return core.math.cos(x); }
> > auto sin(creal z) @safe pure nothrow @nogc
> > auto sin(ireal y) @safe pure nothrow @nogc
> >
> > So we have some of this:
> >
> > conj(z:someValue);
> > abs(x:someValue);
> > sin(y:someValue);
> >
> > Now that parameter names are apart of the function's API, this
> > inconsistency starts to matter as changing it breaks the API.
> > Will druntime/phobos try to come up with standard names for
> > these situations?  Will we try to fix these names before
> > integrating support for named parameters?  If we need to change
> > names later, what will the policy be for druntime/phobos for
> > making parameter name changes when inconsistencies are
> > discovered?
> >
> > Also consider the case when overloads use different parameter
> > names.  std.math.sin uses 'z' for creal arguments and 'y' for
> > ireal arguments.  This can cause issues during refactor as one
> > needs to re-check all parameter names when changing types of
> > arguments. i.e.
> >
> > sin(z:someValue);
> >
> > If you change the type of someValue from creal to ireal, then
> > this would still call the creal overload, perhaps unexpectedly.
>
> I took some time to go through the "std.array" module to see how
> many potential issues it might have.  Here's what I saw:
>
>
>
> -------------------------------------------------------------------------------
> different overloads of split use different parameter names
> -------------------------------------------------------------------------------
>
> > S[] split(S)(S s) @safe pure
> > auto split(alias isTerminator, Range)(Range range)
> > auto split(Range, Separator)(Range range, Separator sep)
>
> split(s: value);
> split(range: value);
>
> -------------------------------------------------------------------------------
> different overloads of "array" use different parameter names
> -------------------------------------------------------------------------------
>
> > ForeachType!Range[] array(Range)(Range r)
> > ForeachType!(PointerTarget!Range)[] array(Range)(Range r)
> > CopyTypeQualifiers!(ElementType!String,dchar)[]
> > array(String)(scope String str)
>
> array(r: value);
> array(str: value);
>
> -------------------------------------------------------------------------------
> Generic Range parameters use many different names 'r', 'range',
> 'ror', 'stuff', 's'
> -------------------------------------------------------------------------------
> > auto split(alias isTerminator, Range)(Range range)
> > ForeachType!Range[] array(Range)(Range r)
> > ForeachType!(PointerTarget!Range)[] array(Range)(Range r)
> > ElementEncodingType!(ElementType!RoR)[] join(RoR, R)(RoR ror,
> > scope R sep)
> > ElementEncodingType!(ElementType!RoR)[] join(RoR, E)(RoR ror,
> > scope E sep)
> > ElementEncodingType!(ElementType!RoR)[] join(RoR)(RoR ror)
> > T[] replace(T, Range)(T[] subject, size_t from, size_t to,
> > Range stuff)
> > ElementType!S[] replicate(S)(S s, size_t n)
>
> split(r: value);
> array(range: value);
> join(ror: value);
> replace(subject: value1, from: value2, to: value3, stuff: value4);
> replicate(s: value, n: 100);
>
> -------------------------------------------------------------------------------
> functions that take 2 arguments but have different parameter names
> -------------------------------------------------------------------------------
> > CommonType!(T[], U[]) overlap(T, U)(T[] a, U[] b) @trusted
> > pure nothrow bool sameHead(T)(in T[] lhs, in T[] rhs)
> > pure nothrow bool sameTail(T)(in T[] lhs, in T[] rhs)
>
> overlay(a: value1, b: value2);
> sameHead(lhs: value1, rhs: value2);
>
> -------------------------------------------------------------------------------
> sometimes an array is passed with 'a', sometimes with 'array',
> sometimes 'arr'
> -------------------------------------------------------------------------------
> > void insertInPlace(T, U...)(ref T[] array, size_t pos, U stuff)
> > auto staticArray(size_t n, T)(scope T a)
> > auto staticArray(size_t n, T)(scope T a, out size_t rangeLength)
> > Appender!(E[]) appender(A : E[], E)(auto ref A array)
> > RefAppender!(E[]) appender(P : E[]*, E)(P arrayPtr)
> > struct Appender(A)
> >     this(A arr) @trusted pure nothrow
>
> insertInPlace(array: value1, pos: value2, stuff: value3);
> staticArray(a: value);
> Appender(arr: value);
>
> -------------------------------------------------------------------------------
> Appender functions use inconsistent parameter names
> -------------------------------------------------------------------------------
> > struct Appender(A)
> >     void reserve(size_t newCapacity)
> >     private void ensureAddable(size_t nelems)
>
> appender.reserve(newCapacity: value);
> appender.ensureAddable(nelems: value);
>
> -------------------------------------------------------------------------------
> Sometimes "length" is spelled out, sometimes it is abbreviated to
> "len"
> -------------------------------------------------------------------------------
> > auto staticArray(size_t n, T)(scope T a, out size_t rangeLength)
> > private size_t appenderNewCapacity(size_t TSizeOf)(size_t
> > curLen, size_t reqLen) @safe pure nothrow
>
> staticArray(a: value, rangeLength: value2);
> appenderNewCapacity(curLen: 100, reqLen: 200);
>
> -------------------------------------------------------------------------------
> appender overloads use different parameter names
> -------------------------------------------------------------------------------
> > Appender!(E[]) appender(A : E[], E)(auto ref A array)
> > RefAppender!(E[]) appender(P : E[]*, E)(P arrayPtr)
>
> appender(array: value);
> appender(arrayPtr: value);

Mmmm, wow.
Yeah, it seems an important pre-req for this DIP to be accepted is
that all standard libraries should have a major pass to make sure all
parameter names are dignified names that we can confidently stand
behind for the rest of time, and also that standard names for common
parameters are decided and proliferated.
"There are 2 hard problems in computer science..."