API Guideline bugs and enhancements


(Erica Sadun) #1

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?


(Paul Cantrell) #2

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.

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:

https://gist.github.com/pcantrell/22a6564ca7d22789315b

The acceptance rate for Apple-guideline-recommended changes come out at only about 50%.

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.

Cheers,

Paul

···

On Jan 5, 2016, at 2:44 PM, Erica Sadun via swift-evolution <swift-evolution@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?

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Douglas Gregor) #3

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

···

On Jan 5, 2016, at 12:44 PM, Erica Sadun via swift-evolution <swift-evolution@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?


(Daniel Steinberg) #4

I agree - there are a few I'd love to see discussed.

I also agree that I appreciate that they are there and so well thought out and presented

···

On Jan 5, 2016, at 4:26 PM, Paul Cantrell via swift-evolution <swift-evolution@swift.org> wrote:

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.

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:

https://gist.github.com/pcantrell/22a6564ca7d22789315b

The acceptance rate for Apple-guideline-recommended changes come out at only about 50%.

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.

Cheers,

Paul

On Jan 5, 2016, at 2:44 PM, Erica Sadun via swift-evolution <swift-evolution@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?

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Howard Lovatt) #5

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@swift.org> wrote:

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


(Rudolf Adamkovič) #6

Great discussion, thanks Erika for bringing this up.

Chiming in with a little question here. The API guidelines say:

Boolean methods and properties should read as assertions about the receiver

I know the document is about APIs but is this also recommended for local variables and constants?

Any thoughts?

Thanks!

R+

···

On 5 Jan 2016, at 22:57, Daniel Steinberg via swift-evolution <swift-evolution@swift.org> wrote:

I agree - there are a few I'd love to see discussed.

I also agree that I appreciate that they are there and so well thought out and presented

On Jan 5, 2016, at 4:26 PM, Paul Cantrell via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

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.

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:

https://gist.github.com/pcantrell/22a6564ca7d22789315b

The acceptance rate for Apple-guideline-recommended changes come out at only about 50%.

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.

Cheers,

Paul

On Jan 5, 2016, at 2:44 PM, Erica Sadun via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@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?

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution