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

Tue Feb 9 03:01:27 CST 2016

Comments inline:

> On Feb 7, 2016, at 9:54 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> 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).

Is this really an overriding concern though? I personally would not choose to optimize for the occasional case of adding a defaulted parameter at the cost of a general naming/labeling convention that we both have expressed some discomfort with.

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

I view this in a quite different way. Breaking a line after 'a.tracksHaving(‘ leaves the reader in quite a bit of suspense! It might be easier to format, but overall readability would suffer.

> 
>> 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)”

I must be interpreting B.1 differently than you intended. It appears to me to be discussing the cases where first arguments *can* be unlabeled. You seem to be implying here that it says that the first argument *must* be unlabeled when it forms a part of a grammatical phrase, otherwise move(from: a, to: b) would be fine. As I read the guidelines, though, only B.2 (which I would modify) requires moveFrom(a, to: b), because of the preposition. What am I not getting here?

—CK

> 
>> 
>> 
>> —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
> 
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution