<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=""><br class=""><div><blockquote type="cite" class=""><div class="">On Jan 5, 2016, at 12:44 PM, Erica Sadun 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 style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><span style="font-family: Palatino-Roman;" class="">Are API Design Guideline improvement discussions in scope for the Swift Evolution list and if not, where would they go?</span></div><div class=""><div class=""><br class=""></div><div class="">For example, the current Swift API Design Guidelines follow these rules more or less.<div class=""><ul class=""><li class="">Use imperative verb phrases for mutating methods: x.reverse(), x.sort(), x.tweak()</li><li class="">Use noun phrases for non-mutating methods: x.distanceTo(...), idx.successor()</li></ul></div><div class="">Seems to me the rules should actually be along the lines of:</div><div class=""><ul class=""><li class="">Use verb phrases to declare procedural methods, whether or not they mutate an instance or just produce side effects: x.reverse(), x.sort(), x.tweak(), x.perform(), x.dispatch(), x.send()</li><li class="">Use noun phrases to describe values returned by a functional method: x.distanceTo(y), index.successor() (This admittedly leaves further issues around other functional methods, for example, seq.separatedBySequence(seq) and int.strideTo(other: Self, step:Self.Stride), etc. )</li></ul></div></div></div><div class="">Are enhancements for API Design Guidelines an area for community involvement? Where would you start a discussion about the rules? Would modifications involve formal proposals?</div></div></div></blockquote><br class=""></div><div>We’re going to bring the API Design Guidelines, standard library changes, and Clang importer changes up for a public review together. Most of the pieces of this effort are described by the <a href="https://swift.org/blog/swift-3-api-design/" class="">Swift 3 API Design Guidelines blog post</a>, but we have some polishing we want to do before initiating the review.</div><div><br class=""></div><div><span class="Apple-tab-span" style="white-space:pre"> </span>- Doug</div><div><br class=""></div></body></html>