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

[David Waite]

My line of thinking is a close variant of this. Usually if I think of the arguments as a potential data structure I pass into the function, then I name the function as if I was passing them all as a single unlabelled argument. 

Usually I think of this as a tuple, so I’m not distracted by whether or not a formal type is needed.

examples (which work today!):

let origin = (x: 0.0, y:0.0)
func moveTo(x x: Double, y:Double) { print("moved to (\(x), \(y))") }
moveTo(origin)

let userCredentials = (username:”jdoe", password:”abcd1234”) 
func logInWith(username username:String, password:String) -> Bool { return true }
logInWith(userCredentials) // my preferred name, since you are giving access to a user and not to credentials

-DW

> On Jan 24, 2016, at 1:23 PM, Paul Cantrell via swift-evolution <swift-evolution at swift.org> wrote:
> 
<snip>
> Radek had a nice thought in the aforementioned Gihub thread:
> 
>> The rationale being, ifNone doesn't really describe the method … it describes the parameter. Most of the time, the job of the method makes the first parameter obvious (hence the guideline), but here, it doesn't. So the parameter makes sense.
> 
> 
> I’ll give a +1 for these two recommendations from Erica, which run along the same lines as Radek’s thought, but in more thorough detail:
> 
>> On Jan 23, 2016, at 6:33 PM, Erica Sadun via swift-evolution <swift-evolution at swift.org <mailto:swift-evolution at swift.org>> wrote:
>> 
>> 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.
> …
>> 
>> 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)
> 
> I’m not sure we’ve found the perfect, crisp way of saying all this — but I strongly agree that the existing guidelines are too rigid on the question of the first arg label, and Erica’s wording comes the closest I’ve seen to being a viable replacement.
> 
> Cheers,
> 
> Paul
> 
> _______________________________________________
> 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/5de5df13/attachment.html>