[swift-evolution] [Review] SE-0023 API Design Guidelines

[Paul Cantrell]

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

Cheers,

Paul