[swift-evolution] When to use argument labels, part DEUX

[Matthew Judge]

> Gah!  Well if you'd like to post those messages here, you certainly have
> my permission.  It might be good to have them as part of the public
> record.
> 
> -- 
> -Dave
> 

Dave's reply to me inline...

> on Fri Feb 05 2016, Matthew Judge <matthew.judge-AT-gmail.com> wrote:
> 
> I certainly can live with these guidelines (and although I have a
> slight preference for something like move(from: a, to: b), it is only
> a _slight_ preference). However, I do have a suggested tweak to
> A. that I believe maintains clarity of guidance and covers this
> case. (See below inline)
> 
>> On Feb 5, 2016, at 16:32, Dave Abrahams via swift-evolution
>> <swift-evolution at swift.org> wrote:
>> 
>> 
>> Given all the awesome feedback I've gotten on this thread, I went back
>> to the drawing board and came up with something new; I think this one
>> works.  The previously-stated goals still apply:
>> 
>> * describe when and where to use argument labels
>> * require labels in many of the cases people have asked for them
>> * are understandable by humans (this means relatively simple)
>> * preserve important semantics communicated by existing APIs.
>> 
>> Please keep in mind that it is a non-goal to capture considerations we
>> think have a bearing on good names (such as relatedness of parameters):
>> it's to create simple guidelines that have the right effect in nearly
>> all cases.
>> 
>> A. When arguments can't be usefully distinguished from one another, none
>>  should have argument labels, e.g. min(x,y), zip(x,y,z).  
> 
> When arguments' _importance_ can't be usefully distinguished from one
> another, none should have argument labels or _all should have argument
> labels_, e.g. min(x,y), zip(x,y,z), move(from: a, to: b), moveTo(x: a,
> y: b)

That would also imply 

 move(a, b)
 tracksWith(a, b)

are both OK, because the importance of a and b can't be distinguished.

It would also imply that

 min(first: a, second: b) 

is OK.  I don't want any of these to be OK.  Do you?

Even if it didn't have these problems, it's asking people to make a
judgement about importance, which makes the rule harder to apply
consistently, and the only practical effect of your proposed change
seems to be to get your preferred form for move(from: a, to: b).

>> B. Otherwise,
>> 
>> 1. At the call site, a first parameter that has no argument label must
>>    form part of a grammatical phrase that starts with the basename, less
>>    any trailing nouns.  
>> 
>>      print(x)
>>      a.contains(b)
>>      a.mergeWith(b)
>>      a.addGestureRecognizer(x)
>>           ^~~~~~~~~~~~~~~~~ trailing noun
> 
> One other potential concern. I understand (and wholeheartedly agree)
> that GestureRecognizer should be pet of the base name here, but I'm
> not sure I see where the guidance explains it to me.

Ah, I see what you mean.  The rules as written would also allow

   add(gestureRecognizer: x)

Excellent point!  I think the fix is to declare, in B.1., that this form
is to be preferred.

>>    This phrase must have the correct semantic implications, so, e.g.
>> 
>>      a.dismiss(b)           // no, unless a is really dismissing b
>>      a.dismissAnimated(b)   // no, not grammatical
>>      a.dismiss(animated: b) // yes, using a label
>> 
>> 2. If the first argument is part of a prepositional phrase, put the
>>    parenthesis immediately after the preposition. 
>> 
>>      a.encodeWith(b)
>>      a.moveFrom(b, to: c)
>> 
>>    Thus, if words are required for any reason between the preposition
>>    and the first argument, they go into the first argument label.
>> 
>>      a.tracksWith(mediaType: b, composer: c)
>>      a.moveTo(x: 22, y: 99)
>> 
>> Notes: 
>> 
>> a. I would recommend prepositions other than "with" in nearly all
>>  cases, but that's not the point of these rules.
>> b. I can understand the aesthetic appeal of
>> 
>>   a.move(from: b, to: c)
>> 
>>  but I believe it is not a clear enough improvement to justify
>>  additional complexity in the guidelines.
>> 
>> Questions:
>> 
>> 1. I'm not expecting these guidelines to make everybody optimally happy,
>>  all the time, but they shouldn't be harmful.  Are there any cases for
>>  which they produce results you couldn't live with?
>> 
>> 2. Are there any cases where you'd be confused about how to apply these
>>  guidelines?
>> 
>> Thanks in advance for all your valuable input!
>> 
>> P.S. Doug is presently working on generating new importer results, based
>>    on these guidelines, for your perusal.  They should be ready soon.
>> 
>> -- 
>> -Dave
>> 
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160207/6a0c4f6e/attachment.html>