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

[Dave Abrahams]

on Sun Jan 31 2016, Howard Lovatt <swift-evolution at swift.org> wrote:

> I would suggest two language changes that embrace argument labels as the
> norm in Swift:
>
>   1. All arguments, functions and initialisers, to be labelled as the
> default in the language, i.e. no special first argument that is
> unlabelled.
>   2. An argument with a default value may be called by specifying the
> label with no value as well as omitting the value as well as
> specifying the value, e.g. in `Array` the drop methods could be `func
> drop(first n: Int = 1)` and `func drop(last n: Int = 1)` and could be
> called `array.drop(first:)` and `array.drop(last:)` and `array.drop()`
> would be an ambiguity error. Thus two functions replace four in
> `Array`.
>
> With these two changes the guidelines could be:
>
>      "All arguments are labelled, e.g. `moveTo(x: 1.0, y: 0.5)`; unless the
> arguments are truely interchangeable and no further clarification is
> required, e.g. `max(x1, x2)`. The degenerate case of the exception is
> functions with one argument; in which case if no further clarification is
> required then no label is required, e.g. `sort(<)`. Clarification via an
> argument label is required if the call reads better, e.g.
> `array.removeAll(keepCapacity: true)`, or because it is clearer in the case
> of overloads, e.g. `array.append(x)` and `array.append(contentsOf:
> x)`."


These are neat ideas, but again, we're not reviewing core language
changes in this thread.

> On 1 February 2016 at 10:08, Dave Abrahams via swift-evolution <
> swift-evolution at swift.org> wrote:
>
>>
>> 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
>>
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
>>

-- 
-Dave