[swift-evolution] [Review] SE-0023 API Design Guidelines

[Dave Abrahams]

on Fri Jan 22 2016, Erica Sadun <swift-evolution at swift.org> wrote:

> _______________________________________________ swift-evolution mailing list swift-evolution at swift.org 
> https://lists.swift.org/mailman/listinfo/swift-evolution
>
> Current:
>
>   * Use imperative verb phrases for mutating methods: x.reverse(), x.sort(), x.tweak()
>   * Use noun phrases for non-mutating methods: x.distanceTo(...), idx.successor()
>
> Proposed:
>
>   * 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. )
>
> I suggest that mutating methods are just a procedural method (side effect, no return value) vs functional.

Hi Erica,

When you propose a change, could you please explain why you think your
change is an improvement?  

Thanks,
Dave

> -- E
>
>     On Jan 22, 2016, at 2:02 PM, Douglas Gregor via swift-evolution <
>     swift-evolution at swift.org> wrote:
>
>     Hello Swift community,
>    
>     The review of SE-0023"API Design Guidelines" begins now and runs through January 31, 2016. The proposal is
>     available here:
>    
>         https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
>    
>     Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution
>     mailing list at
>    
>         https://lists.swift.org/mailman/listinfo/swift-evolution
>    
>     or, if you would like to keep your feedback private, directly to the review manager. When replying, please try
>     to keep the proposal link at the top of the message:
>    
>         Proposal link:
>        
>             https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
>        
>         Reply text
>        
>             Other replies
>        
>      What goes into a review?
>    
>     The goal of the review process is to improve the proposal under review through constructive criticism and,
>     eventually, determine the direction of Swift. When writing your review, here are some questions you might want
>     to answer in your review:
>    
>       + What is your evaluation of the proposal?
>       + Is the problem being addressed significant enough to warrant a change to Swift?
>       + Does this proposal fit well with the feel and direction of Swift?
>       + If you have used other languages or libraries with a similar feature, how do you feel that this proposal
>         compares to those?
>       + How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
>    
>     More information about the Swift evolution process is available at
>    
>         https://github.com/apple/swift-evolution/blob/master/process.md
>    
>     Thank you,
>    
>     -Doug Gregor
>    
>     Review Manager
>    
>     _______________________________________________
>     swift-evolution mailing list
>     swift-evolution at swift.org
>     https://lists.swift.org/mailman/listinfo/swift-evolution
>
> Current: Use imperative verb phrases for mutating methods: x.reverse(), x.sort(), x.tweak() Use noun phrases for
> non-mutating methods: x.distanceTo(...), idx.successor() Proposed: 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. ) I suggest that mutating
> methods are just a procedural method (side effect, no return value) vs functional. -- E > On Jan 22, 2016, at 2:02
> PM, Douglas Gregor via swift-evolution wrote: > > Hello Swift community, > > The review of SE-0023"API Design
> Guidelines" begins now and runs through January 31, 2016. The proposal is available here: > > 
> https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md > Reviews are an important
> part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at > > 
> https://lists.swift.org/mailman/listinfo/swift-evolution > or, if you would like to keep your feedback private,
> directly to the review manager. When replying, please try to keep the proposal link at the top of the message: > >
> Proposal link: > > https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md > Reply
> text > > Other replies > What goes into a review? > > The goal of the review process is to improve the proposal
> under review through constructive criticism and, eventually, determine the direction of Swift. When writing your
> review, here are some questions you might want to answer in your review: > > What is your evaluation of the
> proposal? > Is the problem being addressed significant enough to warrant a change to Swift? > Does this proposal
> fit well with the feel and direction of Swift? > If you have used other languages or libraries with a similar
> feature, how do you feel that this proposal compares to those? > How much effort did you put into your review? A
> glance, a quick reading, or an in-depth study? > More information about the Swift evolution process is available at
>> > https://github.com/apple/swift-evolution/blob/master/process.md > Thank you, > > -Doug Gregor > > Review
> Manager > > _______________________________________________ > swift-evolution mailing list >
> swift-evolution at swift.org > https://lists.swift.org/mailman/listinfo/swift-evolution
>

-- 
-Dave