<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 22, 2016, at 4:24 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="">_______________________________________________ swift-evolution mailing list<span class="Apple-converted-space"> </span><a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a><span class="Apple-converted-space"> </span><br class=""><a href="https://lists.swift.org/mailman/listinfo/swift-evolution" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br class=""><br class="">Current:<br class=""><br class=""> * Use imperative verb phrases for mutating methods: x.reverse(), x.sort(), x.tweak()<br class=""> * Use noun phrases for non-mutating methods: x.distanceTo(...), idx.successor()<br class=""><br class="">Proposed:<br class=""><br class=""> * Use verb phrases to declare procedural methods, whether or not they mutate an instance or just produce side<br class=""> effects: x.reverse(), x.sort(), x.tweak(), x.perform(), x.dispatch(), x.send()<br class=""> * Use noun phrases to describe values returned by a functional method: x.distanceTo(y), index.successor() (This<br class=""> admittedly leaves further issues around other functional methods, for example, seq.separatedBySequence(seq) and<br class=""> int.strideTo(other: Self, step:Self.Stride), etc. )<br class=""><br class="">I suggest that mutating methods are just a procedural method (side effect, no return value) vs functional.<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="">Hi Erica,</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="">When you propose a change, could you please explain why you think your</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="">change is an improvement? </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="">Thanks,</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=""></div></blockquote><div><br class=""></div><div>I believe the current distinction is misguided in focusing on mutating and non-mutating implementations when the</div><div>differentiation can be viewed from a more general level. There are two ways to distinguish these:</div><div><br class=""></div><div>* Does this method or function have side effects (which is what the current API approach intends to address); and</div><div>* Is this method or function inherently functional or procedural in nature, returning a value or not.</div><div><br class=""></div><div>For example, contrast sort() and sortInPlace(). Even with the current approach they lack a natural clarity. You could easily swap </div><div>them without anything "breaking" in understanding because your solution is conventional, not based on any underlying principle.</div><div><br class=""></div><div>With noun/verb naming, the function name reflects the functional/procedural underlying differentiation. </div><div>* A function produces something: f(x) -> y. </div><div>* A procedure does something: g(x) -> Void</div><div><br class=""></div><div>Under my proposed change, the procedural variation would be sort, sortInPlace, etc. Optional adverbs and near-adverbs</div><div>could distinguish similar versions sortQuickly, sortBalanced, etc.</div><div><br class=""></div><div>The functional would be sortedVersion or with a slight rule tweak that infers the subject of the action, sorted. The adjective modifies a noun, and </div><div>therefore implies the presence of a noun that is not explicitly added to the name.</div><div><br class=""></div><div>I find my approach more principled and more obvious for use to non-native speakers.</div><div><br class=""></div><div>Hopefully this clarifies.</div><div><br class=""></div><div>-- E, finishing dinner and about to go on family time. I'll be around a little longer but not much longer</div><div><br class=""></div><div><br class=""></div><br class=""><blockquote type="cite" class=""><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=""><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="">-- E<br class=""><br class=""> On Jan 22, 2016, at 2:02 PM, Douglas Gregor via swift-evolution <<br class=""> <a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>> wrote:<br class=""><br class=""> Hello Swift community,<br class=""><br class=""> The review of SE-0023"API Design Guidelines" begins now and runs through January 31, 2016. The proposal is<br class=""> available here:<br class=""><br class=""> <a href="https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md" class="">https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md</a><br class=""><br class=""> Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution<br class=""> mailing list at<br class=""><br class=""> <a href="https://lists.swift.org/mailman/listinfo/swift-evolution" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br class=""><br class=""> or, if you would like to keep your feedback private, directly to the review manager. When replying, please try<br class=""> to keep the proposal link at the top of the message:<br class=""><br class=""> Proposal link:<br class=""><br class=""> <a href="https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md" class="">https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md</a><br class=""><br class=""> Reply text<br class=""><br class=""> Other replies<br class=""><br class=""> What goes into a review?<br class=""><br class=""> The goal of the review process is to improve the proposal under review through constructive criticism and,<br class=""> eventually, determine the direction of Swift. When writing your review, here are some questions you might want<br class=""> to answer in your review:<br class=""><br class=""> + What is your evaluation of the proposal?<br class=""> + Is the problem being addressed significant enough to warrant a change to Swift?<br class=""> + Does this proposal fit well with the feel and direction of Swift?<br class=""> + If you have used other languages or libraries with a similar feature, how do you feel that this proposal<br class=""> compares to those?<br class=""> + How much effort did you put into your review? A glance, a quick reading, or an in-depth study?<br class=""><br class=""> More information about the Swift evolution process is available at<br class=""><br class=""> <a href="https://github.com/apple/swift-evolution/blob/master/process.md" class="">https://github.com/apple/swift-evolution/blob/master/process.md</a><br class=""><br class=""> Thank you,<br class=""><br class=""> -Doug Gregor<br class=""><br class=""> Review Manager<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=""> <a href="https://lists.swift.org/mailman/listinfo/swift-evolution" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br class=""><br class="">Current: Use imperative verb phrases for mutating methods: x.reverse(), x.sort(), x.tweak() Use noun phrases for<br class="">non-mutating methods: x.distanceTo(...), idx.successor() Proposed: Use verb phrases to declare procedural methods,<br class="">whether or not they mutate an instance or just produce side effects: x.reverse(), x.sort(), x.tweak(), x.perform(),<br class="">x.dispatch(), x.send() Use noun phrases to describe values returned by a functional method: x.distanceTo(y),<br class="">index.successor() (This admittedly leaves further issues around other functional methods, for example,<br class="">seq.separatedBySequence(seq) and int.strideTo(other: Self, step:Self.Stride), etc. ) I suggest that mutating<br class="">methods are just a procedural method (side effect, no return value) vs functional. -- E > On Jan 22, 2016, at 2:02<br class="">PM, Douglas Gregor via swift-evolution wrote: > > Hello Swift community, > > The review of SE-0023"API Design<br class="">Guidelines" begins now and runs through January 31, 2016. The proposal is available here: > ><span class="Apple-converted-space"> </span><br class=""><a href="https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md" class="">https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md</a><span class="Apple-converted-space"> </span>> Reviews are an important<br class="">part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at > ><span class="Apple-converted-space"> </span><br class=""><a href="https://lists.swift.org/mailman/listinfo/swift-evolution" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a><span class="Apple-converted-space"> </span>> or, if you would like to keep your feedback private,<br class="">directly to the review manager. When replying, please try to keep the proposal link at the top of the message: > ><br class="">Proposal link: > ><span class="Apple-converted-space"> </span><a href="https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md" class="">https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md</a><span class="Apple-converted-space"> </span>> Reply<br class="">text > > Other replies > What goes into a review? > > The goal of the review process is to improve the proposal<br class="">under review through constructive criticism and, eventually, determine the direction of Swift. When writing your<br class="">review, here are some questions you might want to answer in your review: > > What is your evaluation of the<br class="">proposal? > Is the problem being addressed significant enough to warrant a change to Swift? > Does this proposal<br class="">fit well with the feel and direction of Swift? > If you have used other languages or libraries with a similar<br class="">feature, how do you feel that this proposal compares to those? > How much effort did you put into your review? A<br class="">glance, a quick reading, or an in-depth study? > More information about the Swift evolution process is available at<br class=""><blockquote type="cite" class=""><blockquote type="cite" class=""><a href="https://github.com/apple/swift-evolution/blob/master/process.md" class="">https://github.com/apple/swift-evolution/blob/master/process.md</a><span class="Apple-converted-space"> </span>> Thank you, > > -Doug Gregor > > Review<br class=""></blockquote></blockquote>Manager > > _______________________________________________ > swift-evolution mailing list ><br class=""><a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a><span class="Apple-converted-space"> </span>><span class="Apple-converted-space"> </span><a href="https://lists.swift.org/mailman/listinfo/swift-evolution" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br class=""><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="">--<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>