[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