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

Erica Sadun erica at ericasadun.com
Fri Jan 22 18:12:12 CST 2016 

> On Jan 22, 2016, at 4:24 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> on Fri Jan 22 2016, Erica Sadun <swift-evolution at swift.org <mailto:swift-evolution at swift.org>> wrote:
> 
>> _______________________________________________ swift-evolution mailing list swift-evolution at swift.org <mailto:swift-evolution at swift.org> 
>> https://lists.swift.org/mailman/listinfo/swift-evolution <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

I believe the current distinction is misguided in focusing on mutating and non-mutating implementations when the
differentiation can be viewed from a more general level. There are two ways to distinguish these:

* Does this method or function have side effects (which is what the current API approach intends to address); and
* Is this method or function inherently functional or procedural in nature, returning a value or not.

For example, contrast sort() and sortInPlace().  Even with the current approach they lack a natural clarity. You could easily swap 
them without anything "breaking" in understanding because your solution is conventional, not based on any underlying principle.

With noun/verb naming, the function name reflects the functional/procedural underlying differentiation. 
* A function produces something: f(x) -> y. 
* A procedure does something: g(x) -> Void

Under my proposed change, the procedural variation would be sort, sortInPlace, etc. Optional adverbs and near-adverbs
could distinguish similar versions sortQuickly, sortBalanced, etc.

The functional would be sortedVersion or with a slight rule tweak that infers the subject of the action, sorted. The adjective modifies a noun, and 
therefore implies the presence of a noun that is not explicitly added to the name.

I find my approach more principled and more obvious for use to non-native speakers.

Hopefully this clarifies.

-- E, finishing dinner and about to go on family time. I'll be around a little longer but not much longer



> 
>> -- 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 <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 <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 <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 <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 <mailto:swift-evolution at swift.org> > https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>
>> 
> 
> -- 
> -Dave
> 
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org <mailto:swift-evolution at swift.org>
> https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160122/9c1cd471/attachment.html>

More information about the swift-evolution mailing list