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

[Jacob Carlborg]

On 2020-05-12 08:22, Jonathan Marler wrote:

> 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.

I agree.

> 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

Yes, I agree.

> A sleep function that takes milliseconds on the other hand could be 
> helpful:
> 
> sleep(100);
> sleep(msecs:100); // helpful

I disagree. It's much better what we already have. The `sleep` method on 
`Thread` takes a duration, instead of a specific time unit. The duration 
is also encoded in its own type:

Thread.getThis.sleep(100.msecs);
Thread.getThis.sleep(1.seconds); // this works too

I guess one could do this:

Thread.getThis.sleep(duration: 1.seconds);

Not sure if it would help though.

Instead of passing a random integer, we pass a type that encodes the 
meaning of the value. It's also more flexible, because you can create a 
Duration out of many different units.

> Given that, here are a list of conventions:
>
> 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)

I disagree. I think there are very few cases of APIs where a function 
expects a truly generic value. It's better to try to encode the purpose 
or how a value is used in the parameter name. Naming something based on 
what it is rarely useful, we have a much better system for that, which 
is the type system :). For example:

void foo(int* p);
void foo(int* pointer);
void foo(int* ptr);

The signature already contains the information that the parameter is a 
pointer, no need to encode that in the name, be it `pointer`, `ptr` or 
`p`. There are cases where a function accepts a truly generic value, 
like a function that can convert any value to a string:

string toString(T)(T value);
toString(value: 3);

But in this case named arguments don't help much and I think it falls 
under the first category (your example with `floor`). Better to call it 
like:

toString(3);
3.toString();

> msecs
> secs

Same thing as the `sleep` method. Should not be a plain int, should be 
its own type.

Also, we should avoiding having short, abbreviated symbol names (any 
kind of symbol names, not just parameter names). Although it's worse to 
have abbreviated names which are part of the API or show up in generated 
documentation. There are always exceptions, like when abbreviated name 
is more known and common than the actual full name. Examples are: HTTP, 
FTP and so on.

-- 
/Jacob Carlborg