[swift-evolution] When to use argument labels, part DEUX (was: when to use argument labels (a new approach))

[Charles Kissinger]

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)

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.

—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