Discussion Thread: DIP 1030--Named Arguments--Final Review
Jonathan Marler
johnnymarler at gmail.com
Tue May 12 06:22:50 UTC 2020
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.
More information about the Digitalmars-d
mailing list