[swift-evolution] [Review] SE-0023 API Design Guidelines
Dave Abrahams
dabrahams at apple.com
Sat Jan 23 12:51:09 CST 2016
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?
> 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?
> 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."
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.
> 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
More information about the swift-evolution
mailing list