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

Erica Sadun erica at ericasadun.com
Sat Jan 23 18:41:15 CST 2016


> On Jan 23, 2016, at 11:51 AM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> on Fri Jan 22 2016, Erica Sadun <swift-evolution at swift.org> wrote:
> 
>>> 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.
> 
> Okay, I understand what you're driving at, but these don't seem to be
> separate distinctions.  Can you show me a method that's inherently
> functional but has side effects, or inherently procedural but has none?

func loginWithCredential(credential: SomeCredentialType) -> SuccessTokenType? {...}
func printThisValueNicelyFormatted<T>(something: T) {...}

> 
>> 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.
> 
> There's certainly an underlying principle there: that methods that
> mutate the receiver, and have a nonmutating counterpart that instead
> returns a modified *copy* of the receiver, are named with "InPlace"
> suffix.  It's not as general as what you're suggesting, but it's
> something.
> 
> How could one could ever call a nonmutating method that returns a new
> collection "sortInPlace," without causing confusion?  How would people
> interpret "InPlace" as conveying meaningful information?

I could imagine two algorithms, one that limits excess memory by sorting in place, and another 
that uses sort-and-copy-back, so the sort is not done in place. My point is not that this
is ideal naming but that I was addressing the example that was part of the original.

> 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. 
> 
> Two issues with "sortedVersion":
> 
> 1. "Version" is needless for readability.  "Return the list of names,
>   sorted."

I included this to force it to be a noun because I was trying to keep with the
examples used in the original. Which is why I then mentioned using
an inferred noun to preserve succinctness.

> 2. I'm already uncomfortable with the idea that the nonmutating version
>   of the method is longer than the mutating one.  The ed/ing "rule"
>   makes the penalty small enough that I think it's tolerable, but
>   "edVersion" is too much.  Note that the nonmutating methods are the
>   ones used in "method chains," and idiom we very much want to support
>   and keep uncluttered.

I'm going to hold off on responding to this because of the two examples I
gave above about "a method that's inherently functional but has side effects, 
or inherently procedural but has none?"


> 
>> The adjective modifies a noun, and therefore implies the presence of a
>> noun that is not explicitly added to the name.
> 
> IIUC, in the end, your proposal leads to the same result.  I understand
> your desire to generalize to deal with side-effects as a whole rather
> than just mutations of the receiver, but it sounds like you're saying
> there's more to it than just that.  What am I missing (if anything)?
> 
>> 
>> 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>
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
> 
> -- 
> -Dave
> 
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution



More information about the swift-evolution mailing list