[swift-evolution] [Review] SE-0005 Better Translation of Objective-C APIs Into Swift

[Dave Abrahams]

on Thu Jan 28 2016, Jordan Rose <swift-evolution at swift.org> wrote:

> Y'know, I was going to complain about this too, and wrote up an example, complete with call site…
>
> accountStore.account(currentID)
>
> …and then realized that it didn't bother me as much as I
> thought. "account" is a noun, so this is either getting or creating an
> account for me (as if it were a property), and it's going to use
> "currentID" to do it.
>
> I'm very used to "fooWithBar: baz" meaning either "get me the foo that
> has a bar matching baz" or "create me a foo with its bar set to
> baz". 

That's great, when that's what "with" means.

> But I'm not sure this new convention is any worse, now that the base
> name isn't assumed to include the first argument.

The problem is that, I'm guessing at least 50% of the time, "with" is
just used as a vacuous connector to make the method name sound
grammatical, and "fooWithBar" doesn't actually mean the "foo" has-a
"bar."  In these cases, it's actively misleading. I know that's not what
you were posting about, but I felt it had to be said :-/

>
> Jordan
>
>> On Jan 28, 2016, at 0:51, David Hart via swift-evolution <swift-evolution at swift.org> wrote:
>> 
>> Loss of 'with' sounds weird in certain cases:
>> 
>> - func account(identifier identifier: String!) -> ACAccount!
>> + func account(identifier: String!) -> ACAccount!
>> 
>> Sent from my iPhone
>> 
>> On 28 Jan 2016, at 00:31, Douglas Gregor via swift-evolution
>> <swift-evolution at swift.org
>> <mailto:swift-evolution at swift.org>>
>> wrote:
>> 
>>> 
>>>> On Jan 27, 2016, at 10:03 AM, Dave Abrahams via swift-evolution
>>>> <swift-evolution at swift.org
>>>> <mailto:swift-evolution at swift.org>>
>>>> wrote:
>>>> 
>>>> 
>>>> on Wed Jan 27 2016, Matthew Johnson
>>>> <swift-evolution at swift.org
>>>> <mailto:swift-evolution at swift.org>>
>>>> wrote:
>>>> 
>>>>> Doug,
>>>>> 
>>>>> I think this change looks great!  I don’t have time to look through
>>>>> the full patch but did look through quite a bit.  It adds clarity in
>>>>> the vast majority of cases I looked at.
>>>>> 
>>>>> It seems like with-as-separator is a good heuristic for determining
>>>>> when the first parameter is not essential to a good name for the
>>>>> fundamental operation.  I agree with the comments earlier on that in
>>>>> these cases a label for the first parameter is the best approach.
>>>>> 
>>>>> I also really like that this groups methods with the same fundamental
>>>>> operation into overload families where they previously had independent
>>>>> names.  This is a big win IMO.
>>>>> 
>>>>> There is a first-parameter-is-an-ID pattern I noticed after this
>>>>> change.  I show a few examples here, but there are a lot more:
>>>>> 
>>>>> -  func trackWithTrackID(trackID: CMPersistentTrackID) -> AVAssetTrack?
>>>>> +  func track(trackID trackID: CMPersistentTrackID) -> AVAssetTrack?
>>>>> 
>>>>> -  func trackWithTrackID(trackID: CMPersistentTrackID) -> AVFragmentedAssetTrack?
>>>>> +  func track(trackID trackID: CMPersistentTrackID) -> AVFragmentedAssetTrack?
>>>>> 
>>>>> -  func trackWithTrackID(trackID: CMPersistentTrackID) -> AVCompositionTrack?
>>>>> +  func track(trackID trackID: CMPersistentTrackID) -> AVCompositionTrack?
>>>>> 
>>>>> - func discoverUserInfoWithUserRecordID(userRecordID: CKRecordID,
>>>>> completionHandler: (CKDiscoveredUserInfo?, Error?) -> Void)
>>>>> 
>>>>> + func discoverUserInfo(userRecordID userRecordID: CKRecordID,
>>>>> completionHandler: (CKDiscoveredUserInfo?, Error?) -> Void)
>>>>> 
>>>>> The first argument label `trackID` seems like it repeats type
>>>>> information without adding clarity.  I think it would be better to
>>>>> just use `id` here.  It seems like a candidate for heuristics as well.
>>>>> For example, if the type name ends in ID and the label is a suffix of
>>>>> the type name we could just use `id`.  This is a somewhat specific
>>>>> pattern, but IDs are common enough that it might make sense.
>>>> 
>>>> Actually I've been saying for a while that arguments called ID,
>>>> identifier, and name should not be labelled at all in many cases.  Think
>>>> about it.
>>> 
>>> 
>>> Patch where the words “ID”, “Identifier”, and “Name” in a name are considered to match the type “String”:
>>> 
>>> <id-identifier-name-match-string.patch>
>>> 
>>> … and then extending the rule to zap first argument labels named “identifier”, “id”, or “name”:
>>> 
>>> <id-identifier-name-no-first-arg-label.patch>
>>> 
>>> 
>>> (I’m not sure which one of these you meant, or something different):
>>> 
>>> 
>>> 	- Doug
>>> 
>>> _______________________________________________
>>> swift-evolution mailing list
>>> swift-evolution at swift.org
>>> <mailto:swift-evolution at swift.org>
>>> https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave