<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="">Hello all,</div><div class=""><br class=""></div><div class=""><a href="https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160125/007658.html" class="">Just like with SE-0005</a>, I’m overwhelmingly for this proposal. The Guidelines, as a whole do a great job at making Swift APIs more consistent and clearer, and applying them to the Swift stdlib is an important first step.</div><div class=""><br class=""></div><div class="">* * *</div><div class=""><br class=""></div><div class="">Nitpicks, criticisms and suggestions:</div><div class=""><br class=""></div><div class="">== precondition was renamed to require ==</div><div class=""><br class=""></div><div class=""><div class="">This might be confusing to newcomers, as many languages use the word `require` as a keyword for what we'd call `import`. Although a bit more technical, `precondition` is unambiguous and still easily understandable. I feel like `required` does more damage than good.</div></div><div class=""><br class=""></div><div class="">== Removed Type from protocol names ==</div><div class=""><br class=""></div><div class="">Perhaps I’ve missed some discussion about this and I don’t see the context, but I’m not sure this is a positive change.</div><div class=""><br class=""></div><div class="">I fear this might be confusing in practice, at least in some contexts. For example, there's nothing signifying that "Boolean" or "Integer" are protocols and not actual types. Same with “Sequence”, “OptionSet”, etc. Perhaps it doesn't matter because everyone will naturally go for `Bool`, `Int`, and `Array` anyway. But I can imagine a lot of confusion if someone tried that anyway, or perhaps saw that in the autocompletion, or the standard library browser (with no intention of using the protocol).</div><div class=""><br class=""></div><div class="">I’m all for removing unnecessary noise and verbosity, but I think I would err on explicitness side here. It seemed like the -able/-Type convention did a good job disambiguating types you can actually instantiate from protocols, with very little “verbosity cost”.</div><div class=""><br class=""></div><div class="">== sort() => sorted(), sortInPlace() => sort() etc ==</div><div class=""><br class=""></div><div class="">I’m torn on this.</div><div class=""><br class=""></div><div class="">Frankly, I find both the “foo/fooInPlace” and “bar/barred” conventions awkward. Both seem weird. “InPlace” isn’t something I recall seeing anywhere else in API naming, and seems a bizarre way of signifying mutability. “-ed” doesn’t work with all words, so you sometimes have to go with “-ing”, or give up and cry. And then you have inconsistency that “-InPlace” doesn’t seem to have. Also, -ed/-ing can sometimes be difficult to write, especially for non-natives because of the “last letter is doubled” rule for some words.</div><div class=""><br class=""></div><div class="">But my biggest problem with this change is that IMHO we should encourage to use the transforming (non-mutating) variants by default. One way to achieve this as an API designer and slightly push people towards doing what’s considered best practice is to make the preferable variant easier to type. This might be a subtle change, but I think it matters. Before, if you really wanted to mutate something in place, you had to do that extra little bit of work typing “sortInPlace”, whereas what would be preferable most of the time had a simpler, shorter form: “sort” and would appear earlier in autocomplete.</div><div class=""><br class=""></div><div class="">== -ings in argument names ==</div><div class=""><br class=""></div><div class="">I’ve noticed these few tweaks in naming:</div><div class=""><br class=""></div><div class=""><div class=""></div></div><blockquote type="cite" class=""><div class=""><div class="">- mutating func removeAll(keepCapacity keepCapacity: Bool = false)</div><div class="">+ mutating func removeAll(keepingCapacity keepingCapacity: Bool = false)</div></div><div class=""><br class=""></div><div class=""><div class=""> public func transcode<...>(...</div><div class="">- stopOnError: Bool</div><div class="">+ stoppingOnError: Bool</div><div class=""> ) -> Bool</div></div><div class=""><br class=""></div><div class=""> + public init(allocatingCapacity count: Int)</div></blockquote><div class=""><br class=""></div><div class="">I'm against this change. While I'm not fully convinced of the -ed/-ing rule for methods and properties, it does an important job by conveying the non-mutating semantics of a symbol described. In case of argument names, this rationale no longer applies.</div><div class=""><br class=""></div><div class="">The only reason to write "stoppingOnError" instead of "stopOnError" is to make method invocations sound more like real English sentences. This is the conventional Objective-C thinking the Guidelines largely step back from. In my opinion, this is futile and provides no readability benefits in this context. Method invocations are _not_ sentences. It's not English, it's code. And while making method names blatantly gramatically incorrect doesn't help readability, neither does forcing `-ing` endings to all boolean function arguments.</div><div class=""><br class=""></div><div class="">The only thing it does is it adds a few extra characters, an extra word ending the reader has to parse and understand. I know that it's a non-goal to make Swift code as terse as possible, and I'm not arguing for that. But the Guidelines seem to agree that adding extra verbosity _without a good reason_ is a bad thing. Because every extra word and symbol in code just adds to the cognitive load of the reader. And when it doesn't serve a purpose, it just decreases the signal-to-noise ratio.</div><div class=""><br class=""></div><div class="">Plus, as mentioned before, `-ed/-ing` can be tricky to spell for non-natives. This might not be a big deal, but given that this change provides no benefits, it's one more tiny thing you have to be careful not to get wrong when writing Swift.</div><div class=""><br class=""></div><div class="">And it's unnecessary:</div><div class=""><br class=""></div><div class=""> removeAll(keepCapacity: true)</div><div class=""> transcode(foo, bar, stopOnError: true)</div><div class=""><br class=""></div><div class="">Are just as clear and readable as:</div><div class=""><br class=""></div><div class=""> removeAll(keepingCapacity: true)</div><div class=""> transcode(foo, bar, stoppingOnError: true)</div><div class=""><br class=""></div><div class="">And the former isn't gramatically incorrect, because this isn't a sentence.</div><div class=""><br class=""></div><div class="">Apologies for nitpicking on this tiniest possible detail. I just care a lot that we don't create a precedent of trying to make everything sound like English unnecessarily and add verbosity bit by bit.</div><div class=""><br class=""></div><div class="">* * *</div><div class=""><br class=""></div><div class=""><blockquote type="cite" class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><ul class="" style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);"><li class="" style="box-sizing: border-box;">Is the problem being addressed significant enough to warrant a change to Swift?</li><li class="" style="box-sizing: border-box;">Does this proposal fit well with the feel and direction of Swift?</li></ul></div></blockquote><div class="">Yes, and yes, with small details still worth reconsidering.</div></div><div class=""><br class=""></div><div class=""><blockquote type="cite" class=""><span style="color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class="">How much effort did you put into your review? A glance, a quick reading, or an in-depth study?</span></blockquote><br class=""></div><div class=""><div class="">I’ve read the whole proposal, as well as the related proposals, and read the thread for this review.</div></div><div class=""><br class=""></div><div class="">Cross-linking to my SE-0005 review: <a href="https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160125/007658.html" class="">https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160125/007658.html</a></div><div class=""><br class=""></div>Thanks,<br class=""><div class="">
<div class="">— Radek</div>
</div>
<br class=""><div><blockquote type="cite" class=""><div class="">On 22 Jan 2016, at 22:02, Douglas Gregor 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=""><meta http-equiv="Content-Type" content="text/html charset=us-ascii" class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><p style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class="">Hello Swift community,</p><p style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class="">The review of SE-0006 "Apply API Guidelines to the Standard Library" begins now and runs through January 31, 2016. The proposal is available here:</p><blockquote style="box-sizing: border-box; margin: 0px 0px 16px; padding: 0px 15px; border-left-width: 4px; border-left-style: solid; border-left-color: rgb(221, 221, 221); background-color: rgb(255, 255, 255);" class=""><font color="#777777" face="Helvetica Neue, Helvetica, Segoe UI, Arial, freesans, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol" size="3" class=""><a href="https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md" class="">https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md</a></font></blockquote><p style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class="">Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at</p><blockquote style="box-sizing: border-box; margin: 0px 0px 16px; padding: 0px 15px; color: rgb(119, 119, 119); border-left-width: 4px; border-left-style: solid; border-left-color: rgb(221, 221, 221); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><div style="box-sizing: border-box; margin-top: 0px; margin-bottom: 0px;" class=""><a href="https://lists.swift.org/mailman/listinfo/swift-evolution" style="box-sizing: border-box; background-color: transparent; color: rgb(64, 120, 192); text-decoration: none;" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a></div></blockquote><p style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class="">or, if you would like to keep your feedback private, directly to the review manager. When replying, please try to keep the proposal link at the top of the message:</p><blockquote style="box-sizing: border-box; margin: 0px 0px 16px; padding: 0px 15px; border-left-width: 4px; border-left-style: solid; border-left-color: rgb(221, 221, 221); background-color: rgb(255, 255, 255);" class=""><p style="color: rgb(119, 119, 119); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; box-sizing: border-box; margin-top: 0px; margin-bottom: 16px;" class="">Proposal link:</p><blockquote style="box-sizing: border-box; margin: 0px 0px 16px; padding: 0px 15px; border-left-width: 4px; border-left-style: solid; border-left-color: rgb(221, 221, 221);" class=""><div style="box-sizing: border-box; margin-top: 0px; margin-bottom: 0px;" class=""><span style="color: rgb(119, 119, 119); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: inherit;" class=""><a href="https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md" class="">https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md</a></span></div></blockquote><p style="color: rgb(119, 119, 119); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; box-sizing: border-box; margin-top: 0px; margin-bottom: 16px;" class="">Reply text</p><blockquote style="color: rgb(119, 119, 119); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; box-sizing: border-box; margin: 0px; padding: 0px 15px; border-left-width: 4px; border-left-style: solid; border-left-color: rgb(221, 221, 221);" class=""><div style="box-sizing: border-box; margin-top: 0px; margin-bottom: 0px;" class="">Other replies</div></blockquote></blockquote><h5 style="box-sizing: border-box; margin-top: 1em; margin-bottom: 16px; line-height: 1.4; font-size: 1em; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; background-color: rgb(255, 255, 255);" class=""><a id="user-content-what-goes-into-a-review-1" class="anchor" href="https://github.com/apple/swift-evolution#what-goes-into-a-review-1" aria-hidden="true" style="box-sizing: border-box; background-color: transparent; color: rgb(64, 120, 192); text-decoration: none; display: inline-block; padding-right: 2px; margin-left: -18px; line-height: 1.1;"><span aria-hidden="true" class="octicon octicon-link" style="box-sizing: border-box; font-weight: normal; font-size: 16px; line-height: 1; font-family: octicons; display: inline-block; text-rendering: auto; -webkit-font-smoothing: antialiased; -webkit-user-select: none; vertical-align: middle; visibility: hidden;"></span></a>What goes into a review?</h5><p style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class="">The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of Swift. When writing your review, here are some questions you might want to answer in your review:</p><ul style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><li style="box-sizing: border-box;" class="">What is your evaluation of the proposal?</li><li style="box-sizing: border-box;" class="">Is the problem being addressed significant enough to warrant a change to Swift?</li><li style="box-sizing: border-box;" class="">Does this proposal fit well with the feel and direction of Swift?</li><li style="box-sizing: border-box;" class="">If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?</li><li style="box-sizing: border-box;" class="">How much effort did you put into your review? A glance, a quick reading, or an in-depth study?</li></ul><p style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class="">More information about the Swift evolution process is available at</p><blockquote style="box-sizing: border-box; margin: 0px 0px 16px; padding: 0px 15px; color: rgb(119, 119, 119); border-left-width: 4px; border-left-style: solid; border-left-color: rgb(221, 221, 221); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><div style="box-sizing: border-box; margin-top: 0px; margin-bottom: 0px;" class=""><a href="https://github.com/apple/swift-evolution/blob/master/process.md" style="box-sizing: border-box; background-color: transparent; color: rgb(64, 120, 192); text-decoration: none;" class="">https://github.com/apple/swift-evolution/blob/master/process.md</a></div></blockquote><p style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class="">Thank you,</p><p style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class="">-Doug Gregor</p><p style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class="">Review Manager</p></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>