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

[Dave Abrahams]

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).



-- 
-Dave