[swift-evolution] [Review] SE-0023 API Design Guidelines
cantrell at pobox.com
Sun Jan 31 13:26:40 CST 2016
> 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.
More information about the swift-evolution