The current API guideline suggests using xxx for mutating methods and either xxxed or xxxing for non-mutating, functional methods. I would suggest refine these rules to:<div><br></div><div> 1. For mutating methods and get and set properties use an imperative verb phrase, e.g. `x.sort()`, use `xxx`.</div><div> 2. For others use:</div><div> 2.a. For eagerly evaluated, get-only properties or non-mutating methods, e.g. `x.sorted()`, use `xxxed`. In particular in `let s = x.sorted()`, `s` does not change if `x` subsequently changes.</div><div> 2.b. For lazily evaluated<font size="2"><span style="background-color:rgba(255,255,255,0)">, get-only properties or non-mutating methods, e.g. `x.mapping(...)`, use `xxxing`. In particular in `let m = x.mapping()`, `m` does change if `x` changes.</span></font></div><div><font size="2"><span style="background-color:rgba(255,255,255,0)"><br></span></font></div><div><font size="2"><span style="background-color:rgba(255,255,255,0)">I am proposing using the name to identify when the evaluation happens.</span></font></div><div><br>On Saturday, 9 January 2016, Douglas Gregor via swift-evolution <<a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a>> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><br><div><blockquote type="cite"><div>On Jan 5, 2016, at 12:44 PM, Erica Sadun via swift-evolution <<a href="javascript:_e(%7B%7D,'cvml','swift-evolution@swift.org');" target="_blank">swift-evolution@swift.org</a>> wrote:</div><br><div><div style="word-wrap:break-word"><div><span style="font-family:Palatino-Roman">Are API Design Guideline improvement discussions in scope for the Swift Evolution list and if not, where would they go?</span></div><div><div><br></div><div>For example, the current Swift API Design Guidelines follow these rules more or less.<div><ul><li>Use imperative verb phrases for mutating methods: x.reverse(), x.sort(), x.tweak()</li><li>Use noun phrases for non-mutating methods: x.distanceTo(...), idx.successor()</li></ul></div><div>Seems to me the rules should actually be along the lines of:</div><div><ul><li>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>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>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></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/" target="_blank">Swift 3 API Design Guidelines blog post</a>, but we have some polishing we want to do before initiating the review.</div><div><br></div><div><span style="white-space:pre-wrap"> </span>- Doug</div><div><br></div>
<img src="https://u2002410.ct.sendgrid.net/wf/open?upn=Vm9j-2B2K6zLqxUFTO82XA8HV2TThDz5lA3-2F-2Fpeujw7DR4ajAwUmVLourZUyHIT7HfhonJfEmjSGUl-2FvTFqFekXPYIk3aPRzW8EhddOR-2F22hdnKGjzxAQd4bgDbL2lo6pXqnjdo69ltgQ-2FcMpJNDb-2FZLWGiVlENtRJHsovgKYY6ZCRhDCH-2F21vYoRn98uMdJwXaGQ5J2Hb3k9VhyaAjqZ-2BUTQDOO3moFekYVJflFc0FZk-3D" alt="" width="1" height="1" border="0" style="min-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">
</div>
</blockquote></div><br><br>-- <br>-- Howard.<br>