Discussion Thread: DIP 1030--Named Arguments--Final Review

[Jonathan Marler]

On Monday, 11 May 2020 at 11:37:07 UTC, Mike Parker wrote:
> This is the discussion thread for the Final Review of DIP 1030, 
> "Named Arguments":
>
> https://github.com/dlang/DIPs/blob/7d114c93edb02d8fc4b05f0716bdb6057905fec2/DIPs/DIP1030.md
>
> The review period will end at 11:59 PM ET on May 25, or when I 
> make a post declaring it complete. Discussion in this thread 
> may continue beyond that point.
>
> 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, etc.
>
> However, if you have any specific feedback on how to improve 
> 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
>
> And my blog post on the difference between the Discussion and 
> Feedback threads:
>
> https://dlang.org/blog/2020/01/26/dip-reviews-discussion-vs-feedback/
>
> Please stay on topic here. I will delete posts that are 
> completely off-topic.

I'd really like to see the DIP include a proposal on parameter 
naming conventions for the standard libraries before we enable 
this.

For example, Walter mentioned in the discussion thread that when 
creating function wrappers for external APIs, we should use the 
same name from the original function. (see 
https://forum.dlang.org/post/r1us6g$11gs$1@digitalmars.com). 
However I don't see this convention mentioned anywhere in the DIP 
and I don't think the choice to do it this way is "self-evident".

Coming up with conventions after we enable this could cause quite 
a bit of headache and debate about when to create wrappers to 
support old parameter name overloads and how much time before we 
remove the deprecations.  There will be much less "friction" to 
fix these names if we do so before enabling the feature.

Here's a start for how these conventions could look:

Parameter Naming Conventions
---------------------------------------------------------------------
First, the parameter names of a function should only be modified 
if exposing the names helps the caller in some way.  For example, 
you needn't bother with the name of the parameter in a function 
such as "floor":

floor(x);
floor(x:x); // not helpful

A sleep function that takes milliseconds on the other hand could 
be helpful:

sleep(100);
sleep(msecs:100); // helpful

Given that, here are a list of conventions:

1. When wrapping another API, use the names from the original.

For example, all Windows functions should use the names from the 
original Windows headers and documentation.

2. Common generic parameter names

p (generic pointer argument, prefer this over ptr or pointer)
s (generic string argument, prefer this over str or string)
i (generic integer argument)
msecs
secs

3. ...


I feel that including a set of conventions in the DIP will be 
worth the effort now, and save us from alot of effort later, even 
if it ends up delaying this feature to a degree.