[swift-evolution] When to use argument labels, part DEUX
Dave Abrahams
dabrahams at apple.com
Sat Feb 6 23:35:27 CST 2016
on Sat Feb 06 2016, Daniel Steinberg <swift-evolution at swift.org> wrote:
> Thanks for this Dave - I really like this document.
>
> I had a few nits but spent a day away from it and came back and think
> that this codifies much of what I’d love to see and I’d be happy
> following it.
>
> What I particularly like is that it presents APIs from the perspective of the caller.
>
> I don’t know if the following is part of this proposal, but I think
> one thing that might helpfully be discussed is how we refer to these
> methods when speaking or writing about them. To me this only matters
> in methods where there are argument labels - but it matters.
>
> For example, in Objective-C, the selector would make it easy for us to
> agree that the method name is moveFrom:to:. How do we refer to
> moveFrom(a, to: b)? Is it the moveFrom method?
I think "moveFrom" is perfectly adequate for conversation if it's
unambiguous, but if you want to be precise it'd be "moveFrom(_:to:)".
Note that because Swift has overloading based on type, even that name is
not necessarily enough to fully disambiguate between methods.
> This also helps me care less whether it is moveFrom(a, to: b) or
> move(from:a, to: b) - I too prefer the second version but not enough
> to object and not at all if the “to" is part of how we refer to this
> method.
>
> Thoughts? Or is that out of scope?
It's sort of tangential, but I hope I've answered your question above.
>
> Best,
>
> Daniel
>
>> On Feb 5, 2016, at 4: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
More information about the swift-evolution
mailing list