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

[Dave Abrahams]

on Sun Feb 07 2016, Charles Kissinger <swift-evolution at swift.org> wrote:

> Looking over these guidelines again, I think I would be quite happy with them given one very simple change to Rule 2:
>
> If the first argument is part of a prepositional phrase WITH MULTIPLE
> OBJECTS, put the parenthesis immediately after the preposition.
>
> This eliminates the need for:
>
> a.tracksHaving(mediaType: b)
>
> which I think is inferior to:
>
> a.tracksHavingMediaType(b)

The downside with the latter is that it doesn't scale up.  When you want
to add a second criterion, you can't just add a defaulted parameter; you
have to change the signature (breaking code) or add one or more
overloads (creating cognitive weight for users).

It's a (relatively speaking) minor issue, but IMO not glomming all that
description into the base name also results in code that's easier to
format in a balanced way, simply because there's a natural place to
break the line after the parenthesis.

> On the other hand, functions like:
>
> a.tracksWith(mediaType: b, composer: c)
> a.moveTo(x: 22, y: 99)
>
> would remain as is, because there are multiple objects for the preposition.
>
> This also neatly solves the ‘moveFrom(a to: b)’ problem. There are two
> separate prepositional phrases involved, 'from a' and 'to b', each
> with a single object, so:
>
> move(from: a to: b)
>
> is, I believe, fully compatible with the guidelines.

I don't see anything in the guidelines I've proposed, even with your
modification, that would cause "from" to be placed inside the
parentheses.  The way I read it this case still falls right into B1,
resulting in "moveFrom(a, to: b)"

>
>
> —CK
>
>> On Feb 5, 2016, at 1:32 PM, 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).  
>> 
>> 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
>> 
>>     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
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave