[swift-evolution] Labels was Re: [swift-evolution-announce] [Review] SE-0023 API Design Guidelines

[Erica Sadun]

Again, I've taken some time and attempted to write this up more coherently:

https://github.com/erica/SwiftStyle/blob/master/ArgumentLabels.md <https://github.com/erica/SwiftStyle/blob/master/ArgumentLabels.md>

I've also updated the topic, so I can follow this more easily.

-- Erica


> On Jan 24, 2016, at 1:43 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> on Sat Jan 23 2016, Erica Sadun <swift-evolution at swift.org> wrote:
> 
>> Dave,
>> 
>> I typoed on the second and I was insufficiently clear on my point. Trying again:
>> 
>> 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)
>> 
>> 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)
>> 
>> The coupling between x and y, username and password, (and yes it is a judgement call) 
>> should be considered as a reason to employ an external label.
> 
> Yeah, I understand what you're going for, but it doesn't seem very crisp
> to me.  Personally, I think Rob Mayoff's suggestion
> 
>  loginAs(me, password: mySecret)
> 
> is pretty awesome.  Fundamentally, the username is driving the call, and
> the password is a piece of dependent information you have to match up to
> it.
> 
>> I had included the following as a counter example:
>> 
>> addLineToPoint(p1, withWidth: 25.0)
>> 
>> In this call, the point and width have no natural or compelling relationship and there's no reason to
>> create an external label for the first argument. This example follows the standard
>> Swift call approach.
> 
> Up to now, there has been no "standard Swift call approach," so I don't
> know what this means.
> 
>> Differentiate related calls whose implementations are distinguished by their
>> parameters, as you would with initializers, using first parameter labels.
>> 
>> Instead of loginWithUserName("blah", password: "...") and loginWithCredential(myCredential),
>> prefer:
>> 
>> login(userName: "blah", password: "...")
>> login(credential: myCredential)
> 
> So, how does this proposal improve understandability of use-sites?
> 
>> And to reply to another point raised in-thread:
>> 
>> When working with standard library calls, retain APIs even if they are
>> not sufficiently clear from a Swift design perspective rather than
>> wrapping-the-cat to provide a Swift interface that doesn't really
>> exist. (As the call is just a redirection.)
>> 
>> For example, prefer
>> 
>> let x = pow(2.0, 5.0)
>> 
>> to
>> 
>> let x = raise(2.0, toPower: 5.0)
>> 
>> In this example, the two arguments for pow are not specified as this call is sourced
>> externally and follows the naming convention for math.h.
> 
> This idea is already captured in the guidelines; the reasons to use
> "pow(x, y)" are the same as the reasons to use "sin(x)".
> 
> -- 
> -Dave
> 
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160124/dc9c4508/attachment.html>