<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><br class=""><div><blockquote type="cite" class=""><div class="">On Jan 23, 2016, at 1:21 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=""><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">on Fri Jan 22 2016, Erica Sadun <</span><a href="mailto:swift-evolution@swift.org" style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class="">swift-evolution@swift.org</a><span style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">> wrote:</span><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><blockquote type="cite" style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><blockquote type="cite" class="">On Jan 22, 2016, at 5:26 PM, Michael Wells via swift-evolution<br class=""><<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>> wrote:<br class=""><br class=""><br class=""><blockquote type="cite" class="">On Sat, Jan 23, 2016 at 12:00 AM, David Owens II via<br class=""></blockquote></blockquote><br class=""><blockquote type="cite" class=""><blockquote type="cite" class="">swift-evolution<br class=""><<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a><br class=""><<a href="mailto:swift-evolution@swift.org" class="">mailto:swift-evolution@swift.org</a>>><br class="">wrote:<br class=""><blockquote type="cite" class="">Compensate For Weak Type Information as needed to clarify a parameter’s role.<br class=""><br class="">Especially when a parameter type is NSObject, Any, AnyObject, or a<br class="">fundamental type such Int or String, type information and context<br class="">at the point of use may not fully convey intent. In this example,<br class="">the declaration may be clear, but the use site is vague:<br class=""><br class="">func add(observer: NSObject, for keyPath: String)<br class="">grid.add(self, for: graphics) // vague<br class=""><br class="">To restore clarity, precede each weakly-typed parameter with a noun describing its role:<br class=""><br class="">func addObserver(_ observer: NSObject, forKeyPath path: String)<br class="">grid.addObserver(self, forKeyPath: graphics) // clear<br class=""></blockquote><br class=""></blockquote><br class="">Where this rule feels clumsy to me is in code such as<br class=""><br class="">func loginWithUsername(username: String, password: String) -> Bool<br class=""><br class="">vs.<br class=""><br class="">func login(username: String, password: String) -> Bool<br class=""><br class="">But maybe it just takes some time to get used to the style.<br class=""></blockquote><br class="">Consider an exception rule:<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. So<br class=""><br class="">login(username: String, password:String)<br class="">moveTo(x: Double, y: Double)<br class=""></blockquote><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">used as</span><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class=""> login("dave", password: secret)</span><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class=""> moveTo(width, y: height)</span><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">?</span><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">I can't imagine you meant the latter one.</span><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><blockquote type="cite" style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class="">but<span class="Apple-converted-space"> </span><br class=""><br class="">addLineToPoint(p1: CGPoint, withThickness: CGFloat)<br class=""></blockquote><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class=""> addLineToPoint(origin, withThickness: CGFloat)</span><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">?</span><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">I don't see what salient information the word "Point" is adding here.</span><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""></div></blockquote><div><br class=""></div><div>Dave,</div><div><br class=""></div><div>I typoed on the second and I was insufficiently clear on my point. Trying again:</div><div><br class=""></div><div><b class="">Prefer external names for the first parameter when the natural</b></div><div><div class=""><b class="">semantic relationship between the parameters is stronger than their<br class="">relation to the operation.</b> </div><div class=""><br class=""></div><div class="">For example, the following calls use labels for the first parameter:</div><div class=""><br class=""></div><div class=""><font face="Courier" class="">login(userName: "blah", password: "...")</font></div><div class=""><font face="Courier" class="">moveTo(x: 50.0, y: 30.0)</font></div><div class=""><br class=""></div><div class="">This example is contrary to Swift's normal naming scheme which integrates the</div><div class="">first argument into the function or method name, for example:</div><div class=""><br class=""></div><div class=""><font face="Courier" class="">loginWithUserName("blah", password: "...")</font></div><div class=""><font face="Courier" class="">moveToX(50.0, y: 30.0)</font></div><div class=""><br class=""></div><div class="">The coupling between x and y, username and password, (and yes it is a judgement call) </div><div class="">should be considered as a reason to employ an external label.</div><div class=""><br class=""></div><div class="">I had included the following as a counter example:</div><div class=""><br class=""></div><div class=""><div class=""><font face="Courier" class="">addLineToPoint(p1, withWidth: 25.0)</font></div></div><div class=""><br class=""></div><div class="">In this call, the point and width have no natural or compelling relationship and there's no reason to</div><div class="">create an external label for the first argument. This example follows the standard</div><div class="">Swift call approach.</div><div class=""><br class=""></div><div class=""><b class="">Differentiate related calls whose implementations are distinguished by their</b></div><div class=""><b class="">parameters, as you would with initializers, using first parameter labels.</b></div><div class=""><b class=""><br class=""></b></div><div class="">Instead of loginWithUserName("blah", password: "...") and loginWithCredential(myCredential),</div><div class="">prefer:</div><div class=""><br class=""></div><div class=""><font face="Courier" class="">login(userName: "blah", password: "...")</font></div><div class=""><font face="Courier" class="">login(credential: myCredential)</font></div><div class=""><br class=""></div><div class="">And to reply to another point raised in-thread:</div><div class=""><br class=""></div><div class=""><div><b class="">When working with standard library calls, retain APIs even if they are</b></div><div><b class="">not sufficiently clear from a Swift design perspective rather than wrapping-the-cat</b></div><div><b class="">to provide a Swift interface that doesn't really exist. (As the call is just a redirection.)</b></div><div><br class=""></div><div>For example, prefer</div><div><br class=""></div><div><font face="Courier" class="">let x = pow(2.0, 5.0)</font></div><div><br class=""></div><div>to</div><div><br class=""></div><div><font face="Courier" class="">let x = raise(2.0, toPower: 5.0)</font></div><div><br class=""></div><div>In this example, the two arguments for pow are not specified as this call is sourced</div><div>externally and follows the naming convention for math.h.</div></div><div class=""><br class=""></div><div class="">-- Erica</div><div class=""><br class=""></div></div><br class=""><blockquote type="cite" class=""><div class=""><span style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">--<span class="Apple-converted-space"> </span></span><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">-Dave</span><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">_______________________________________________</span><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">swift-evolution mailing list</span><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><a href="mailto:swift-evolution@swift.org" style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class="">swift-evolution@swift.org</a><br style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><a href="https://lists.swift.org/mailman/listinfo/swift-evolution" style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a></div></blockquote></div><br class=""></body></html>