[swift-evolution] API Guideline bugs and enhancements

[Douglas Gregor]

> On Jan 5, 2016, at 12:44 PM, Erica Sadun via swift-evolution <swift-evolution at swift.org> wrote:
> 
> Are API Design Guideline improvement discussions in scope for the Swift Evolution list and if not, where would they go?
> 
> For example, the current Swift API Design Guidelines follow these rules more or less.
> Use imperative verb phrases for mutating methods: x.reverse(), x.sort(), x.tweak()
> Use noun phrases for non-mutating methods: x.distanceTo(...), idx.successor()
> Seems to me the rules should actually be along the lines of:
> 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()
> 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. )
> 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?

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 Swift 3 API  Design Guidelines blog post <https://swift.org/blog/swift-3-api-design/>, but we have some polishing we want to do before initiating the review.

	- Doug

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160108/42660c0d/attachment.html>