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

[Douglas Gregor]

> On Apr 3, 2016, at 1:56 PM, Shawn Erickson <shawnce at gmail.com> wrote:
> 
> 
> 
> On Sun, Apr 3, 2016 at 1:27 PM Shawn Erickson <shawnce at gmail.com <mailto:shawnce at gmail.com>> wrote:
> On Sun, Apr 3, 2016 at 6:41 AM Michel Fortin via swift-evolution <swift-evolution at swift.org <mailto: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.

I think the best English verb for this construction is “emplace”:

	http://www.dictionary.com/browse/emplace

It means “to put in position”, and is always used with an object (the noun). It’s basically free from incorrect connotations because it’s obscure enough that most English speakers won’t know it, and is easily searchable for English- and non-English speakers alike.

	- Doug

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