<html><head><meta http-equiv="Content-Type" content="text/html charset=us-ascii"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class="">Again, I've taken some time and attempted to write this up more coherently:</div><div class=""><br class=""></div><div class=""><a href="https://github.com/erica/SwiftStyle/blob/master/ArgumentLabels.md" class="">https://github.com/erica/SwiftStyle/blob/master/ArgumentLabels.md</a></div><div class=""><br class=""></div><div class="">I've also updated the topic, so I can follow this more easily.</div><div class=""><br class=""></div><div class="">-- Erica</div><div class=""><br class=""></div><br class=""><div><blockquote type="cite" class=""><div class="">On Jan 24, 2016, at 1:43 PM, Dave Abrahams via swift-evolution <<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div class=""><br class="">on Sat Jan 23 2016, Erica Sadun <<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>> wrote:<br class=""><br class=""><blockquote type="cite" class="">Dave,<br class=""><br class="">I typoed on the second and I was insufficiently clear on my point. Trying again:<br class=""><br class="">Prefer external names for the first parameter when the natural<br class="">semantic relationship between the parameters is stronger than their<br class="">relation to the operation. <br class=""><br class="">For example, the following calls use labels for the first parameter:<br class=""><br class="">login(userName: "blah", password: "...")<br class="">moveTo(x: 50.0, y: 30.0)<br class=""><br class="">This example is contrary to Swift's normal naming scheme which integrates the<br class="">first argument into the function or method name, for example:<br class=""><br class="">loginWithUserName("blah", password: "...")<br class="">moveToX(50.0, y: 30.0)<br class=""><br class="">The coupling between x and y, username and password, (and yes it is a judgement call) <br class="">should be considered as a reason to employ an external label.<br class=""></blockquote><br class="">Yeah, I understand what you're going for, but it doesn't seem very crisp<br class="">to me. Personally, I think Rob Mayoff's suggestion<br class=""><br class=""> loginAs(me, password: mySecret)<br class=""><br class="">is pretty awesome. Fundamentally, the username is driving the call, and<br class="">the password is a piece of dependent information you have to match up to<br class="">it.<br class=""><br class=""><blockquote type="cite" class="">I had included the following as a counter example:<br class=""><br class="">addLineToPoint(p1, withWidth: 25.0)<br class=""><br class="">In this call, the point and width have no natural or compelling relationship and there's no reason to<br class="">create an external label for the first argument. This example follows the standard<br class="">Swift call approach.<br class=""></blockquote><br class="">Up to now, there has been no "standard Swift call approach," so I don't<br class="">know what this means.<br class=""><br class=""><blockquote type="cite" class="">Differentiate related calls whose implementations are distinguished by their<br class="">parameters, as you would with initializers, using first parameter labels.<br class=""><br class="">Instead of loginWithUserName("blah", password: "...") and loginWithCredential(myCredential),<br class="">prefer:<br class=""><br class="">login(userName: "blah", password: "...")<br class="">login(credential: myCredential)<br class=""></blockquote><br class="">So, how does this proposal improve understandability of use-sites?<br class=""><br class=""><blockquote type="cite" class="">And to reply to another point raised in-thread:<br class=""><br class="">When working with standard library calls, retain APIs even if they are<br class="">not sufficiently clear from a Swift design perspective rather than<br class="">wrapping-the-cat to provide a Swift interface that doesn't really<br class="">exist. (As the call is just a redirection.)<br class=""><br class="">For example, prefer<br class=""><br class="">let x = pow(2.0, 5.0)<br class=""><br class="">to<br class=""><br class="">let x = raise(2.0, toPower: 5.0)<br class=""><br class="">In this example, the two arguments for pow are not specified as this call is sourced<br class="">externally and follows the naming convention for math.h.<br class=""></blockquote><br class="">This idea is already captured in the guidelines; the reasons to use<br class="">"pow(x, y)" are the same as the reasons to use "sin(x)".<br class=""><br class="">-- <br class="">-Dave<br class=""><br class="">_______________________________________________<br class="">swift-evolution mailing list<br class=""><a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a><br class="">https://lists.swift.org/mailman/listinfo/swift-evolution<br class=""></div></div></blockquote></div><br class=""></body></html>