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

[Colin Cornaby]

(Just catching up on this thread)

I’m actually still a little uncomfortable with this new translation of the Obj-C API, although maybe like you I just need to let my brain chew on it for a while. :)

Part of the issue I think is the original function name. As a query function, if I was rewriting this in Swift, I feel like I’d write it as something like “fetchAccount”. accountWith isn’t ideal, but it implies there is some sort of lookup mechanism that is going to happen, and it implies some sort of expense. Just “account” by itself becomes fuzzier than I’d like.

I think there are definitely cases where the with is unnecessary. Looking through Metal under Swift 3 tonight I found…
func newTextureWith(descriptor: MTLTextureDescriptor, offset: Int, bytesPerRow: Int) -> MTLTexture

Totally unnecessary here. I have all the context with “newTexture” that I need. I have a reasonable idea of what the function is doing.

If I was doing lookup, similarly I don’t know if I’d like this function name:
func texture(descriptor: MTLTextureDescriptor) -> MTLTexture

Especially in this context (in a scenario where maybe newTexture didn’t exist or someone is lost with the API), without more context, it sounds like this function might be used for texture creation. Although I admit “textureWith” wouldn’t be a huge improvement in that respect, but it does seem like a small improvement. Or maybe I just need to think about that one for a bit.

> On Jan 28, 2016, at 12:03 PM, Jordan Rose via swift-evolution <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". But I'm not sure this new convention is any worse, now that the base name isn't assumed to include the first argument.
> 
> Jordan
> 
> 
> 
>> On Jan 28, 2016, at 0:51, David Hart via swift-evolution <swift-evolution at swift.org <mailto: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 <mailto: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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160201/4ee10e3a/attachment.html>