<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=""><br class=""><div><blockquote type="cite" class=""><div class="">On Jan 30, 2016, at 8:49 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 Fri Jan 29 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="">It suddenly occurs to me it's almost the 31st and I haven't actually<br class="">responded to the proposal as a proposal. <br class=""></blockquote><br class="">Thanks for taking the time to do this, Erica. I'm going to take issue<br class="">with some of your feedback below, but please know this is motivated by a<br class="">desire to make the most of your contribution. I think your feedback is<br class="">valuable, but much of the signal is getting lost.<br class=""></div></div></blockquote><div><br class=""></div><div>No worries. "Low SNR" is my street name.</div><br class=""><blockquote type="cite" class=""><div class=""><div class=""><blockquote type="cite" class="">First, I'd entirely eliminate the guidance in the "Be Grammatical"<br class="">section and move the section with boolean assertions and property<br class="">names to Special Instructions.<br class=""></blockquote><br class="">I *think* I may know why you want to eliminate the first part, but I<br class="">have no clue why you think it'd be better to move the other part.<br class="">Statements like these don't really provide much useful feedback, because<br class="">we can't tell what problems you think you're solving.<br class=""></div></div></blockquote><div><br class=""></div><div>I consider the great Hungarian war settled and am happy with its outcome</div><div>as discussed in the other email.</div><br class=""><blockquote type="cite" class=""><div class=""><div class=""><blockquote type="cite" class="">* The protocol question is big and wide as well, and I have written<br class="">on-list: it's not "the role of a protocol to describe implementation<br class="">details...Going that way leads you to over-designated hungarian-esque<br class="">guidelines that I'd rather keep loose, friendly, and sensible."<br class=""></blockquote><br class="">You have written that, but nothing in the guidelines suggests describing<br class="">implementation details.<br class=""></div></div></blockquote><div><br class=""></div><div>I think this mostly got settled under separate thread. Pulling stuff together.</div><div><br class=""></div><div>The guidance says: "<i class="">Protocols that describe what something is should read as nouns (e.g. ). </i></div><div><i class="">Protocols that describe a capability should be named using the suffixes ,</i></div><div><i class="">ible , or ing (e.g. Equatable , ProgressReporting ).</i>"</div><div><br class=""></div><div>Nitpickage: </div><div><br class=""></div><div>"should be named using -ble or -ing suffixes (e.g. Equatable, ProgressReporting)". (no "a/i" mismatch, easier to read, <a href="http://thespellingblog.blogspot.com/2008/12/spelling-words-ending-in-able-and-ible.html" class="">http://thespellingblog.blogspot.com/2008/12/spelling-words-ending-in-able-and-ible.html</a>)</div><div><br class=""></div><div>Substance, mostly picking up from stuff you've said in response:</div><div><br class=""></div><div>Protocols should express well-defined, testable semantics. Their names should express those</div><div>semantics in a clear and succinct matter., specifically by naming what a conforming type <i class="">is</i> (use nouns),<i class=""> </i></div><div><i class="">does</i> (use -ing suffixes), or a <i class="">capacity</i> it provides (use -ble suffixes). For example, a protocol can be a `Collection` </div><div>or `DataSource`. It can do `ProgressReporting` or `DownloadProcessing`. It can provide the capability for being </div><div>`Equatable` or `IntegerInitializable`.</div><div><br class=""></div><div>Additionalage:</div><div><br class=""></div><div>Matthew J and I add: <a href="https://github.com/apple/swift-evolution/pull/60" class="">https://github.com/apple/swift-evolution/pull/60</a> to introduce precise conventional</div><div>meanings for conversion suffixes. (Createable, Convertible, Representable), which I'd love for you to consider</div><div>under the SE-0023 API Design Guidelines review. I think it's applicable.</div><div><br class=""></div><blockquote type="cite" class=""><div class=""><div class=""><blockquote type="cite" class=""><br class=""></blockquote>* With regard to argument labels, I'd like to add two rules,<br class=""><blockquote type="cite" class="">as detailed in-thread and written about here: ArgumentLabels.md<br class=""><<a href="https://github.com/erica/SwiftStyle/blob/master/ArgumentLabels.md" class="">https://github.com/erica/SwiftStyle/blob/master/ArgumentLabels.md</a>><br class=""><br class="">Differentiate related calls whose implementations are distinguished by<br class="">their parameters, as you would with initializers, using first<br class="">parameter labels. Instead of loginWithUserName("blah", password:<br class="">"...") and loginWithCredential(myCredential), prefer:<br class=""><br class="">login(userName: "blah", password: "...")<br class="">login(credential: myCredential)<br class="">This approach emphasizes the action being taken (login) and demotes<br class="">the actual arguments involved in performing that action. In doing so,<br class="">they require labels to differentiate which implementation of that<br class="">action is to be used.<br class=""><br class="">and<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=""></blockquote><br class="">That rule doesn't work for any one-parameter methods, unless you think<br class="">they should never have first argument labels.<br class=""></div></div></blockquote><div><br class=""></div><div>The rule only applies to tightly coupled arguments so by definition there have to be at least 2 of them</div><div>for this rule to make any sense.</div><br class=""><blockquote type="cite" class=""><div class=""><div class=""><br class=""><blockquote type="cite" 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="">constructColor(red: 0.2, green: 0.3, blue: 0.1)<br class=""><br class="">This example is contrary to Swift's normal naming scheme which<br class="">integrates the first argument into the function or method name, for<br class="">example:<br class=""><br class="">loginWithUserName("blah", password: "...")<br class="">moveToX(50.0, y: 30.0)<br class="">constructColorWithRed(0.2, green: 0.3, blue: 0.1)<br class=""><br class="">The relationships between (x, y), (username, password), and (red,<br class="">green, blue) are strong enough to allow you to make a judgement call<br class="">to employ an external label.<br class=""><br class="">The following shows a counter-example.<br class=""><br class="">addLineTo(p1, withWidth: 25.0)<br class=""><br class="">In this call, the point and width have no natural<br class="">relationship. There's no reason to create an external label for the<br class="">first argument so this example follows the standard Swift call<br class="">approach.<br class=""></blockquote><br class="">Thanks again for your feedback, Erica. If you'd care to clarify any of<br class="">the points above, that'd be extra awesome.<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>