Re: [swift-evolution] API Guideline bugs and enhancements

[Howard Lovatt via swift-evolution]

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
> > 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 , but we have some
> polishing we want to do before initiating the review.
>
> - Doug
>
>

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

Re: [swift-evolution] API Guideline bugs and enhancements

[Rudolf Adamkovič via swift-evolution]

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 
>  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 
> > 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 
>>> > 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 
>> 
>  ___
> 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