[swift-evolution] API Guideline bugs and enhancements

[Howard Lovatt]

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:

  1. For mutating methods and get and set properties use an imperative verb
phrase, e.g. `x.sort()`, use `xxx`.
  2. For others use:
    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.
    2.b. For lazily evaluated, 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.

I am proposing using the name to identify when the evaluation happens.

On Saturday, 9 January 2016, Douglas Gregor via swift-evolution <
swift-evolution at swift.org> wrote:

>
> On Jan 5, 2016, at 12:44 PM, Erica Sadun via swift-evolution <
> swift-evolution at swift.org
> <javascript:_e(%7B%7D,'cvml','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
>
>

-- 
-- Howard.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160418/2b6023b3/attachment.html>