[swift-evolution] [Review] SE-0059: Update API Naming Guidelines and Rewrite Set APIs Accordingly

[Dave Abrahams]

on Sun Apr 03 2016, Michel Fortin <swift-evolution at swift.org> wrote:

>> What is your evaluation of the proposal?
>
> I don't like "form" as a prefix. To me there is no difference between
> `union` and `formUnion`: both sounds functional-style, and actually
> the second one perhaps a bit more to my ears. There's basically two
> dictionary definitions of "form":
>
> 1. "bring together parts or combine to create (something)" which to me
> implies a new value is created, and
> 2. "make or fashion into a certain shape or form" which would imply
> that the material you start with is transformed, which is apparently
> the intended meaning and also the reverse meaning from the above.

When you tell a group of people to “form a circle,” you're asking them
to assume the shape of a circle, not to create a new identity.  That's
the way I view “formUnion.”

> I mean, doesn't this make sense as an API?
>
> 	let donut = baker.formDonut(dough) // non-mutating

Not if you account for the rule that verb phrases and side-effects are
always linked.

> Perhaps instead of "form" we could use "become" as a prefix when the
> operation is naturally described by a noun. That would seem less
> ambiguous to me:
>
> 	a.becomeUnion(b)
> 	a.becomeIntersection(b)
> 	a.becomeSuccessor(b)
>
> It's a bit passive, but I find it fits well when the operation is a
> noun.

The latter one doesn't work at all for the actual use case.  It sounds
like you're telling a to become the successor of b.  In fact, it's 

     someCollection.formSuccessor(&someIndex)

which is updating someIndex to point at its successor position.

> And there's no way the term lends itself to non-mutating cases without
> things becoming nonsensical:
>
> 	let donut = baker.becomeDonut(dough) // non-mutating?

I agree that is more unambiguous.

>> Is the problem being addressed significant enough to warrant a change to Swift?
>
> I'm still not entirely convinced any of this is better than the
> `InPlace` suffix we had before. `InPlace` might be ugly visually and
> grammatically, but seems to be the clearest at expressing the intent.
>
>> Does this proposal fit well with the feel and direction of Swift?
>
> There is no question that using a verb instead of the `InPlace` suffix
> makes things fits better with the other API guidelines.
>
>> If you have used other languages or libraries with a similar
>> feature, how do you feel that this proposal compares to those?
>
> N/A
>
>> How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
>
> Read the guideline and API diffs, thought about a few alternative wording, looked in my dictionary.

-- 
Dave