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

My reply back to Dave...



> On Feb 5, 2016, at 22:04, Dave Abrahams <dabrahams at apple.com> wrote:
> 
> 
>> 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)

I would not want either of these two allowed. 

I just realized that the rules as you wrote them imply "if A applies, ignore B"... I was thinking of A as special case that modifies the rules in B. So if we refactor the guidelines to:

Guideline 1: B.1
Guideline 2: B.2
Special Case: A.1

I believe they are both still covered by B.1 

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

I think omit needless words still covers this. I would say zip() is clearly still covered by B.1 as well. (With my above refactoring of the guidelines.)

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

I forgot to carry this comment forward from my reply to the other thread, but I think constraining this to the first parameter is needlessly specific. 

"At the call site, parameter(s) that have no argument label must..." still seems to do what we want and covers a case like zip(x,y,z) without needing to apply a special rule. (Although there is an implied "and" to make it a sentence: "zip x, y, and z")

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

I'm not sure how prevalent my way of thinking about method names is, but I would argue the following both have argument labels, they've just been pulled to the left of the parenthesis:

a.mergeWith(b)
a.addGestureRecognizer(b)

So in my mind, B.2 really is just "move the first argument label into the base name unless B.1 prevents it" which then covers addGestureRecognizer and addObserver styled method names.

> 
>>>   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
> 
> -- 
> -Dave
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160207/844aa0a0/attachment.html>