[swift-evolution] [Review] SE-0023 API Design Guidelines
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
>> 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.”
More information about the swift-evolution