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

Dave Abrahams dabrahams at apple.com
Tue Feb 9 08:42:21 CST 2016 

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

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

Why do you think it's inferior?

>> 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 not an *overriding* concern; it's one of many.  BTW, I don't
consider “some discomfort” on anyone's part to be an overriding concern
either.  Most of these changes make Cocoa traditionalists wildly
uncomfortable.  While I have compassion for that, the key thing is
understandability of Swift code into the future.  

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

Suspense is good in these cases; it means the reader isn't going to stop
at the end of the line.  One should feel relief only when one has taken
in all the important parts of the call.

> It might be easier to format, but overall readability would suffer.

I don't see how

  a.long.line.ending.with.tracksHavingMediaType(
    mp3)

is any more readable than

  a.long.line.ending.with.tracksHaving(
    mediaType: mp3)

to me, it's less readable.

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


Maybe I was mistaken. I'm working on new wording that allows "from" to
move inside the parens under the same guideline that results in argument
labels for all arguments when the method is a factory function.  I'll
let you know when that's ready.

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

-- 
-Dave

More information about the swift-evolution mailing list