[swift-evolution] [Guidelines, First Argument Labels]: Prepositions inside the parens

[Douglas Gregor]

> On Feb 11, 2016, at 4:00 PM, Dave Abrahams <dabrahams at apple.com> wrote:
> 
> 
> on Thu Feb 11 2016, Douglas Gregor <dgregor-AT-apple.com> wrote:
> 
>>> On Feb 11, 2016, at 11:57 AM, Dave Abrahams <dabrahams at apple.com> wrote:
>>> 
>>> 
>>> on Thu Feb 11 2016, Douglas Gregor <dgregor-AT-apple.com <http://dgregor-at-apple.com/>> wrote:
>>> 
>> 
>>>>> On Feb 11, 2016, at 10:53 AM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
>>>>> 
>>>>> 
>>>>> on Thu Feb 11 2016, Charles Kissinger <swift-evolution at swift.org> wrote:
>>>>> 
>>>> 
>>>>>> FWIW, I think these new guidelines strike a very nice balance between
>>>>>> all of the competing concerns. The result of applying them to some of
>>>>>> my own code could best be described as “different but not unpleasant”
>>>>>> ;-)
>>>>>> 
>>>>>> In looking over the diffs, one nice result I didn’t expect is that
>>>>>> moving the prepositional phrases into the first argument label seems
>>>>>> to increase the speed with which I absorb the general intent of a
>>>>>> function -- the “at a glance” understanding -- by moving a “detail”
>>>>>> (important as it might be) into the parameter list. (The split
>>>>>> prepositional phrases had the opposite effect for me.)
>>>>> 
>>>>> That's nice!  What do you think about moving “of” back out of the
>>>>> parens?  Does that help or hurt?
>>>> 
>>>> And lo!, a diff appeared!
>>>> 
>>>> 	https://github.com/apple/swift-3-api-guidelines-review/commit/3f965346f1edea804a9bc6223d2824f43687e92f
>>> 
>>> Hmm, looking at these I think it's really the “lonely ‘of’” that we want
>>> to pull out of the parens, i.e.
>>> 
>>>       indexOf(x)
>>> 
>>> but not
>>> 
>>>       animal(ofGenus: .reptile)
>> 
>> Lonely “of”s move to the base name:
>> 
>> 	https://github.com/apple/swift-3-api-guidelines-review/commit/f9cb1c468eee7cb827000911cad36e9e1b7fdfbc
> 
> Doug and I reviewed these, and we don't think they work.  The right
> criterion for cocoa seems to be “pull ‘of’ into the base name unless—as
> Jordan suggested—it means “having.”  
> 
> Fortunately that seems to be easily determined.  After looking at all
> the APIs in Cocoa, “of” in the base name means “having” exactly when it
> is followed by one of the following words: “type,” “types,” “kind,”
> “size,” “length,” and maybe “stage” (we're trying to analyze
> removeModifiersOfStage
> <https://developer.apple.com/library/mac/documentation/SceneKit/Reference/SCNParticleSystem_Class/#//apple_ref/doc/uid/TP40014177-CH1-SW132>
> to figure out how “of”is being used—assistance welcome).

https://github.com/apple/swift-3-api-guidelines-review/commit/7778b21bccd01d30a74155bf0e47f4a68a07b45f


	- Doug