<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="">I love that the team has released API Design Guidelines and find them very helpful. One piece of advice, however, seems to be at odds with current Standard Library practice.<div class=""><br class=""></div><div class="">Currently the methods sort() and sortInPlace() are the non-mutating and mutating versions of sorting a collection. Similarly, there are pairs of methods in Set named union() and unionInPlace(), intersect() and intersectInPlace() and so on.</div><div class=""><br class=""></div><div class="">I think the x(), xInPlace() pairs are easier to use than the previous pairs. the inPlace variant is clearly the mutating implementation as the name tells me that the operation is going to be performed in place on the reciever.</div><div class=""><br class=""></div><div class="">Previously the sort methods were named sort() and sorted(). I never could remember which is which. The API Guidelines currently recommend this sort/sorted practice as opposed to sort/sortInPlace. </div><div class=""><br class=""></div><div class="">I know this is a small issue - given the many important tasks you have before you, but I’d love to see the section “Be Grammatical” revised to update the following advice to match current practice. The following two are not consistent with library practices.</div><div class=""><br class=""></div><ul style="box-sizing: border-box; margin: 1em 0px; padding: 0px 0px 0px 40px; list-style-position: initial; list-style-image: initial; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, Arial, Verdana, sans-serif; font-size: 18px;" class=""><li style="box-sizing: border-box; margin: 0px; padding: 0px;" class=""><p style="box-sizing: border-box; margin: 0px 0px 1.5em; padding: 0px;" class="">Uses of <strong style="box-sizing: border-box;" class="">mutating methods should read as imperative verb phrases</strong>, e.g., <code class="highlighter-rouge" style="box-sizing: border-box; font-size: 14px; font-family: Menlo, Consolas, Monaco, 'Courier New', monospace, serif; color: rgb(0, 0, 0); padding: 3px 8px; white-space: pre-line; border: 1px solid rgb(229, 229, 229); background-color: rgb(247, 247, 247);">x.reverse()</code>, <code class="highlighter-rouge" style="box-sizing: border-box; font-size: 14px; font-family: Menlo, Consolas, Monaco, 'Courier New', monospace, serif; color: rgb(0, 0, 0); padding: 3px 8px; white-space: pre-line; border: 1px solid rgb(229, 229, 229); background-color: rgb(247, 247, 247);">x.sort()</code>, <code class="highlighter-rouge" style="box-sizing: border-box; font-size: 14px; font-family: Menlo, Consolas, Monaco, 'Courier New', monospace, serif; color: rgb(0, 0, 0); padding: 3px 8px; white-space: pre-line; border: 1px solid rgb(229, 229, 229); background-color: rgb(247, 247, 247);">x.append(y)</code>.</p></li></ul><div class=""> and</div><div class=""><br class=""></div><div class=""><ul style="box-sizing: border-box; margin: 1em 0px; padding: 0px 0px 0px 40px; list-style-position: initial; list-style-image: initial; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, Arial, Verdana, sans-serif; font-size: 18px;" class=""><li style="box-sizing: border-box; margin: 0px; padding: 0px;" class="">When <strong style="box-sizing: border-box;" class="">a mutating method is described by a verb, name its non-mutating counterpart</strong> according to the <strong style="box-sizing: border-box;" class="">“ed/ing” rule</strong>, e.g. the non-mutating versions of <code class="highlighter-rouge" style="box-sizing: border-box; font-size: 14px; font-family: Menlo, Consolas, Monaco, 'Courier New', monospace, serif; color: rgb(0, 0, 0); padding: 3px 8px; white-space: pre-line; border: 1px solid rgb(229, 229, 229); background-color: rgb(247, 247, 247);">x.sort()</code> and <code class="highlighter-rouge" style="box-sizing: border-box; font-size: 14px; font-family: Menlo, Consolas, Monaco, 'Courier New', monospace, serif; color: rgb(0, 0, 0); padding: 3px 8px; white-space: pre-line; border: 1px solid rgb(229, 229, 229); background-color: rgb(247, 247, 247);">x.append(y)</code> are <code class="highlighter-rouge" style="box-sizing: border-box; font-size: 14px; font-family: Menlo, Consolas, Monaco, 'Courier New', monospace, serif; color: rgb(0, 0, 0); padding: 3px 8px; white-space: pre-line; border: 1px solid rgb(229, 229, 229); background-color: rgb(247, 247, 247);">x.sorted()</code> and <code class="highlighter-rouge" style="box-sizing: border-box; font-size: 14px; font-family: Menlo, Consolas, Monaco, 'Courier New', monospace, serif; color: rgb(0, 0, 0); padding: 3px 8px; white-space: pre-line; border: 1px solid rgb(229, 229, 229); background-color: rgb(247, 247, 247);">x.appending(y)</code>.</li></ul><div class=""><br class=""></div><div class="">The Swift Programming Language Guide 2.1 reflects the actual use of sort()</div></div><div class=""><br class=""></div><div class=""><span style="color: rgb(65, 65, 65); font-family: Helvetica, Arial, sans-serif; font-size: 14px; background-color: rgb(255, 255, 255);" class="">For example, the Swift standard library provides both the mutating method </span><code class="code-voice" style="border: 0px; font-size: 0.85em; margin: 0px; outline: 0px; padding: 0px; vertical-align: baseline; color: rgb(128, 128, 128); font-family: Menlo, monospace; word-wrap: break-word;">sortInPlace()</code><span style="color: rgb(65, 65, 65); font-family: Helvetica, Arial, sans-serif; font-size: 14px; background-color: rgb(255, 255, 255);" class=""> and the nonmutating method </span><code class="code-voice" style="border: 0px; font-size: 0.85em; margin: 0px; outline: 0px; padding: 0px; vertical-align: baseline; color: rgb(128, 128, 128); font-family: Menlo, monospace; word-wrap: break-word;">sort()</code><span style="color: rgb(65, 65, 65); font-family: Helvetica, Arial, sans-serif; font-size: 14px; background-color: rgb(255, 255, 255);" class=""> to collections whose generator element conforms to the </span><code class="code-voice" style="border: 0px; font-size: 0.85em; margin: 0px; outline: 0px; padding: 0px; vertical-align: baseline; color: rgb(128, 128, 128); font-family: Menlo, monospace; word-wrap: break-word;">Comparable</code><span style="color: rgb(65, 65, 65); font-family: Helvetica, Arial, sans-serif; font-size: 14px; background-color: rgb(255, 255, 255);" class="">protocol. </span></div><div class=""><br class=""></div><div class="">Note that in the API Guidelines sort() should be mutating and in actuality (and in the Language Guide) sort() is non-mutating.</div><div class=""><br class=""></div><div class=""><br class=""></div><div class=""><br class=""></div><div class=""><br class=""></div><div class="">Thank you,</div><div class=""><br class=""></div><div class="">Daniel</div></body></html>