<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="">I’ll second Erica on wanting a place to discuss the API guidelines. In general, I like their general approach and philosophy — very much so! — but I also have concerns about some of the details. For example, I totally agree with Erica’s suggestion that all methods with side effects should be verbs, not just ones that mutate the receiver.</div><div class=""><br class=""></div><div class="">You can read here a detailed writeup on the sticking points I hit trying to put the guidelines into practice on a real-world project:</div><div class=""><br class=""></div><div class=""><div class=""><a href="https://gist.github.com/pcantrell/22a6564ca7d22789315b" class="">https://gist.github.com/pcantrell/22a6564ca7d22789315b</a></div></div><div class=""><br class=""></div><div class="">The acceptance rate for Apple-guideline-recommended changes come out at only about 50%.</div><div class=""><br class=""></div><div class="">I realize that guidelines are just guidelines, but that seems like a bit of an easy out if the guidelines doc is meant to help unify the style of disparate Swift libraries.</div><div class=""><br class=""></div><div class="">Cheers,</div><div class=""><br class=""></div><div class="">Paul</div><div class=""><br class=""></div><br class=""><div><blockquote type="cite" class=""><div class="">On Jan 5, 2016, at 2: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>
<img src="https://u2002410.ct.sendgrid.net/wf/open?upn=zCg-2FSGF9Wk188a6c55kLyEbrj7YhaXxFEHM-2F-2B0YAlzXczXhBHMPbVrYKqms57EyCesq2afPQr8naeOBcgJgj5n0DYz2JH6exJzwcq2GLUN-2FCmKjk79GufX8r314ih4NjIO8IJIIKUooMyJaCMlW7J3cbhFFc0-2B7V8xUB-2BcTd9xCQuii-2BcZqBllesM6N0W0xE4UcJLPKzt-2FmDehJUcNqwd9VAaRLe156-2BWstqjlX2cB0-3D" alt="" width="1" height="1" border="0" style="height:1px !important;width:1px !important;border-width:0 !important;margin-top:0 !important;margin-bottom:0 !important;margin-right:0 !important;margin-left:0 !important;padding-top:0 !important;padding-bottom:0 !important;padding-right:0 !important;padding-left:0 !important;" class="">
</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>