[swift-evolution] When to use argument labels, part DEUX

[Dave Abrahams]

on Sat Feb 06 2016, Charles Kissinger <swift-evolution at swift.org> wrote:

>> On Feb 5, 2016, at 11:16 PM, Douglas Gregor via swift-evolution
>> <swift-evolution at swift.org> wrote:
>> 
>> 
>>> On Feb 5, 2016, at 1:32 PM, Dave Abrahams via swift-evolution
>
>>> <swift-evolution at swift.org
>>> <mailto:swift-evolution at swift.org>>
>>> wrote:
>>> 
>>> 
>>> Given all the awesome feedback I've gotten on this thread, I went back
>>> to the drawing board and came up with something new; I think this one
>>> works.  The previously-stated goals still apply:
>> 
>>> [snip goals]
>> 
>>> P.S. Doug is presently working on generating new importer results, based
>>>     on these guidelines, for your perusal.  They should be ready soon.
>> 
>> 
>> Here’s a link:
>> 
>> 	https://github.com/apple/swift-3-api-guidelines-review/pull/10/files
>> <https://github.com/apple/swift-3-api-guidelines-review/pull/10/files>
> Well, I might be the only one, but I don’t like these diffs. There are
> only a few cases where I don’t prefer the original function
> signature. Function names ending in prepositions with no objects look
> odd to me. 

I understand that feeling.  Doug *really* understands it.  In the end,
though, we couldn't convince ourselves that it was odd enough to be a
problem, and I think you just need to get used to it.

> It seems like a strange choice to make the split in the middle of the
> prepositional phrase.

See my description of the tradeoffs in my recent reply to Matthew Judge.

> If, as now proposed, the description of the main focus of the function
> call is going to be moved from the function name to a label for the
> first parameter, why not just drop the preposition entirely? 
>
> As in:
>
> func copy(zone zone: Zone = nil) -> AnyObject
> func loadValuesAsynchronously(keys keys: [String], completionHandler handler: (() -> Void)? = nil)
> func tracks(mediaType mediaType: String) -> [AVAssetTrack]

1. I'm not sure I buy the idea that the first argument of a method is
   the main focus—why not the receiver?  But that's probably beside your
   point...

2. I don't understand the logic of this statement.  It sounds analogous
   to, “well, if we're going to move my car from the garage to the
   street, why don't we just go ahead and throw out its windshield?”

3. Let's not throw out the baby with the bathwater!  The preposition
   helps describe the relationship of the argument to the method
   (although as I've mentioned, “with” is a particularly weak and
   over-used preposition).


> Or put it in the argument label, to keep the prepositional phrase intact:
>
> func copy(withZone zone: Zone = nil) -> AnyObject
> func loadValuesAsynchronously(forKeys keys: [String], completionHandler handler: (() -> Void)? = nil)
> func tracks(withMediaType mediaType: String) -> [AVAssetTrack]

See my aforementioned reply to Matthew about the tradeoffs.

-- 
-Dave