[swift-evolution] [Review] SE-0023 API Design Guidelines
Dave Abrahams
dabrahams at apple.com
Sun Jan 31 17:08:32 CST 2016
on Sun Jan 31 2016, Paul Cantrell <swift-evolution at swift.org> wrote:
>> On Jan 29, 2016, at 10:29 AM, Erica Sadun via swift-evolution <swift-evolution at swift.org> wrote:
>>
>> Differentiate related calls whose implementations are distinguished
>> by their parameters, as you would with initializers, using first
>> parameter labels.
>
>> …
>> Prefer external names for the first parameter when the natural
>> semantic relationship between the parameters is stronger than their
>> relation to the operation.
>>
>> For example, the following calls use labels for the first parameter:
>>
>> login(userName: "blah", password: "...")
>> moveTo(x: 50.0, y: 30.0)
>> constructColor(red: 0.2, green: 0.3, blue: 0.1)
>>
>> This example is contrary to Swift's normal naming scheme which
>> integrates the first argument into the function or method name, for
>> example:
>>
>> loginWithUserName("blah", password: "...")
>> moveToX(50.0, y: 30.0)
>> constructColorWithRed(0.2, green: 0.3, blue: 0.1)
>>
>> The relationships between (x, y), (username, password), and (red,
>> green, blue) are strong enough to allow you to make a judgement call
>> to employ an external label.
>>
>
> An anecdote in support of Erica’s thinking in the ongoing Battle of the First Argument Labels:
>
> I mentioned the ongoing swift-evolution debates to Bret Jackson, one
> of my Macalester colleagues — awesome developer, 3D / VR / HCI
> researcher, tons of C++ experience, never seen Swift before — and
> typed out this example for him:
>
> moveTo(1.0, y: 0.5)
>
> …and then this (he nods approvingly):
>
> moveTo(x: 1.0, y: 0.5)
>
> …and then this:
>
> moveToX(1.0, y: 0.5)
>
> …at which point, before I’d even finished typing it out, he physically
> recoiled in revulsion, threw hand up in front of his face, and let out
> a pained “oh please no!!” I wish I had video of him squirming in his
> chair. It was something to behold.
>
> Thus my N=1 study of Swift newcomers concludes that “moveToX” is horrifying.
a. I agree; it's not me you need to convince.
b. The guidelines working group is reluctant to add special-case
guidelines. It would be better to have one guideline that works for
all the cases where first arguments should have a label, including
those that have only one argument. For example, “first arguments
that are not direct objects should be labeled when it doesn't merely
repeat type information.”
--
-Dave
More information about the swift-evolution
mailing list