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

[Jonathan Marler]

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);