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

[Shawn Erickson]

On Sun, Apr 3, 2016 at 1:27 PM Shawn Erickson <shawnce at gmail.com> wrote:

> On Sun, Apr 3, 2016 at 6:41 AM Michel Fortin via swift-evolution <
> 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.
>>
>> I mean, doesn't this make sense as an API?
>>
>>         let donut = baker.formDonut(dough) // non-mutating
>>
>> 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.
>>
>> 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 also am having difficulty coming to terms with the use of "form" (I am a
> native English speaker). As you note "form" can imply the creation of
> something from parts (more like assembling a new thing) as well as the
> creation of something out of a material say a of block clay (more like
> molding something out of an existing thing). It doesn't seem clear cut to
> me to imply in place mutation.
>
> Additionally my eyes / brain keep seeing "from" instead of "form". This
> type of issue is generally true with any short word made up of the same set
> of letters (made worse since "from" is more common in programming then
> "form"). The mind quickly narrows in on a set of possible words given the
> letters we see and then uses context to help get the correct one and/or
> additional visual parsing to understand the exact ordering of letters (more
> energy expended). Anyway since I keep seeing "from" instead of "form" I
> keep going in the direction of thinking it returns something made from the
> two (or more) items involved (not really sure why "from" goes that
> direction in my head, it could also go the in place direction).
>
> I would prefer something other then "form" (note I just typed "from" by
> mistake)... I think your suggestion of "become" has merit.
>
> y.becomeUnion(x) --reads to me as--> "y become union with x"
> y.formUnion(x) --read to me as--> "y from oops... y forming a union of x"
> y.becomeIntersection(x) --reads to me as--> "y become intersection with x"
> y.formIntersection(x) --read to me as--> "y from oops... y forming an
> intersection with x"
>

After stepping away for a bit and looking at it from the POV of the API of
Set and not in the context of "y" I could read things in the abstract as...

"becomeUnion(with other:Self)" --> "I become a union with other"
"formUnion(with other:Self)" --> "I form a union with other"

No clear winner to me however when used in code "become" still feels more
strongly mutating then "form": y.formUnion(with:x) or y.becomeUnion(with:x)

All in all the API would have mutating in front of it (at least for
structs) and it wouldn't have a return type. It would become clear fairly
quickly as a result (hence learned).

Just still not that happy with "form" but with use my mind would likely
quickly adapt.

-Shawn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160403/6b4df203/attachment.html>