<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=""><div class=""><br class=""></div><div><blockquote type="cite" class=""><div class="">On Jan 22, 2016, at 6:12 PM, Ross O'Brien 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 dir="ltr" class="">How would we apply this to delegate patterns?<div class="">For example, would we keep tableview(tableView:cellForRowAtIndexPath:), or would we switch to delegate(tableView:cellForRowAtIndexPath:) ?</div><div class="">Or perhaps better, for clarity over which protocol is being conformed to / which property of the delegator is calling the function:</div><div class="">dataSource(tableView:cellForRowAtIndexPath:),</div><div class="">delegate(tableView:didSelectRowAtIndexPath:)</div></div></div></blockquote><div><br class=""></div><div>FWIW, I am personally favorable to a more radical-renaming for delegate methods, roughly the below:</div><div><div><div><br class=""></div><div>func numberOfSections(inTableView tableView: UITableView) -> Int // <- against guidelines, but symmetric</div>func numberOfRows(inTableView tableView: UITableView, forSection section: Int) -> Int</div><div><div>func cellForRow(inTableView tableView: UITableView, atIndexPath indexPath: NSIndexPath) -> UITableView</div><div><br class=""></div></div></div><div>…where the rule is to find the “what is this method about” part of the selector, make that the name of the Swift function, and then label each argument as-necessary; the goal is for the methods to read as approximate natural-language sentences.</div><div><br class=""></div><div>This is most definitely *not* in line with conventions, but I have found it to be *much* more readable overall; this is especially true in the case of new APIs (which don’t have the benefit of deep familiarity like the table-view and similar).</div><div><br class=""></div><div>EG, consider the following lightly-edited definition (from some Swift code that needs to be usable from Objective-C):</div><div><br class=""></div><div><div class="">// from a `TransitionAnimatorDelegateProtocol`</div></div><div><div>@objc(transitionAnimator:userInfoForTransitionSender:transitionOrigin:transitionDestination:)</div><div> func transitionUserInfo(</div><div> forAnimator animator: TransitionAnimator,</div><div> sender: AnyObject?,</div><div> origin: TransitionOriginProtocol,</div><div> destination: TransitionDestinationProtocol) -> [String:AnyObject]?</div><div><br class=""></div><div>…which, coming across in Swift, feels a whole lot more readable than the “conventional” approach; I mean really, would anyone out there voluntarily use a name like the below, instead:</div><div><br class=""></div><div>func transtionAnimator(</div><div> animator: TransitionAnimator, </div><div> userInfoForTransitionSender sender: AnyObject?,</div><div> transitionOrigin origin: TransitionOriginProtocol,</div><div><div> transitionDestination destination: TransitionDestination) -> [String:AnyObject]?</div><div><br class=""></div><div>…except out of respect for tradition?</div><div><br class=""></div><div>I’m still processing the overall guidelines.</div><div><br class=""></div></div></div><blockquote type="cite" class=""><div class=""><div class="gmail_extra"><br class=""><div class="gmail_quote">On Sat, Jan 23, 2016 at 12:00 AM, David Owens II via swift-evolution <span dir="ltr" class=""><<a href="mailto:swift-evolution@swift.org" target="_blank" class="">swift-evolution@swift.org</a>></span> wrote:<br class=""><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word" class=""><blockquote type="cite" class=""><div class=""><div class=""><b class="">Compensate For Weak Type Information as needed to clarify a parameter’s role.<br class=""></b></div><div class=""><br class=""></div>Especially when a parameter type is NSObject, Any, AnyObject, or a fundamental type such Int or String, type information and context at the point of use may not fully convey intent. In this example, the declaration may be clear, but the use site is vague:<br class=""><br class=""></div><blockquote style="margin:0 0 0 40px;border:none;padding:0px" class=""><div class=""><div class=""><font face="Menlo" class="">func add(observer: NSObject, for keyPath: String)</font></div></div><div class=""><div class=""><font face="Menlo" class="">grid.add(self, for: graphics) // vague</font></div></div></blockquote><div class=""><br class="">To restore clarity, precede each weakly-typed parameter with a noun describing its role:<br class=""><br class=""></div><blockquote style="margin:0 0 0 40px;border:none;padding:0px" class=""><div class=""><font face="Menlo" class="">func addObserver(_ observer: NSObject, forKeyPath path: String)</font></div><div class=""><div class=""><font face="Menlo" class="">grid.addObserver(self, forKeyPath: graphics) // clear</font></div></div></blockquote></blockquote><div class=""><br class=""></div><div class="">I don’t understand why to compensate for weak type information we put some of that compensation in the name of the function and other parts of it in the [external] name of the parameter.</div><div class=""><br class=""></div><div class="">If we were going to reference functions like this: addObserver:forKeyPath, then I can understand it. But that’s not the plan of record, it’s to do this: addObserver(_:forKeyPath). </div><div class=""><br class=""></div><div class="">Regardless of the default naming scheme, it seems like the rule should be to use external names to clarify that parameters role.</div><div class=""><br class=""></div><div class=""><blockquote style="margin:0px 0px 0px 40px;border:none;padding:0px" class=""><div class=""><font face="Menlo" class="">func add(observer observer: NSObject, forKeyPath path: String)</font></div><div class=""><font face="Menlo" class="">grid.add(observer: self, forKeyPath: graphics)</font></div></blockquote></div><div class=""><br class=""></div><div class="">This promotes a very clear and consistent rule: weak type information should be clarified by the parameter’s external name. There are no exceptions for the first parameter. Otherwise, it seems like there is super fine line between this rule and the next one below. </div><div class=""><br class=""></div><div class="">Additionally, this also alleviates my concerns with the default parameter have _ as the external name by default because this addresses the case when it would be desirable to have that name. Further, the case below handles the case when it’s not.</div><div class=""><br class=""></div><div class=""><br class=""></div><div class=""><div class=""><b class=""></b></div></div><blockquote type="cite" class=""><div class=""><div class=""><b class="">Omit Needless Words. Every word in a name should convey salient information at the use site.<br class=""></b></div><div class=""><br class=""></div>More words may be needed to clarify intent or disambiguate meaning, but those that are redundant with information the reader already possesses should be omitted. In particular, omit words that merely repeat type information:<br class=""><br class=""></div><blockquote style="margin:0 0 0 40px;border:none;padding:0px" class=""><div class=""><div class=""><font face="Menlo" class="">public mutating func removeElement(member: Element) -> Element?</font></div></div><div class=""><div class=""><font face="Menlo" class="">allViews.removeElement(cancelButton)</font></div></div></blockquote><div class=""><br class="">In this case, the word Element adds nothing salient at the call site. This API would be better:<br class=""><br class=""></div><blockquote style="margin:0 0 0 40px;border:none;padding:0px" class=""><div class=""><div class=""><font face="Menlo" class="">public mutating func remove(member: Element) -> Element?</font></div></div><div class=""><div class=""><font face="Menlo" class="">allViews.remove(cancelButton) // clearer</font></div></div></blockquote><div class=""><br class="">Occasionally, repeating type information is necessary to avoid ambiguity, but in general it is better to use a word that describes a parameter’s role rather than its type. See the next item for details.</div></blockquote><div class=""><br class=""></div><div class="">The description here seems to overlap with the “Compensate for Weak Type Information” rule, especially with the clause: “repeating type information”. It may be better to re-work the example to be `removeItem(member: Element)` to make this distinction more clear that it’s not type information being removed.</div><div class=""><br class=""></div><div class="">Also, by clarifying that statement, the above rule change I suggested would be consistent. Type information clarification goes into the external parameter name, functionality clarification goes into the function name. Those are hard-n-fast rules that are straight-forward. </div><div class=""><br class=""></div><div class=""><br class=""></div><div class=""></div><blockquote type="cite" class=""><div class=""><b class="">Be Grammatical</b></div><span class=""><div class=""><b class=""><br class=""></b></div><div class=""><div class="">When a mutating method is described by a verb, name its non-mutating counterpart according to the “ed/ing” rule, e.g. the non-mutating versions of x.sort() and x.append(y) are x.sorted() and x.appending(y).</div></div></span></blockquote><div class=""><br class=""></div><div class="">Is this guideline suggesting that we should design our APIs to generally have both mutating and non-mutaging counterparts?</div><div class=""><br class=""></div><div class="">As other have pointed out, this is also very hard to do all the time. I think the alternatives are worse. It would be nice if there were a way to annotate all member functions as mutating/non-mutating to really by-pass this ambiguity.</div><div class=""><br class=""></div><div class="">Other than the above, the proposal looks pretty good to me.</div><div class=""><br class=""></div><div class="">-David</div><br class=""></div><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="">
<a href="https://lists.swift.org/mailman/listinfo/swift-evolution" rel="noreferrer" target="_blank" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br class="">
<br class=""></blockquote></div><br class=""></div>
_______________________________________________<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></blockquote></div><br class=""></body></html>