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

[Douglas Gregor]

> On Jan 27, 2016, at 10:03 AM, Dave Abrahams via swift-evolution <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”:



… and then extending the rule to zap first argument labels named “identifier”, “id”, or “name”:




(I’m not sure which one of these you meant, or something different):


	- Doug

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160127/d1a6afc5/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: id-identifier-name-match-string.patch
Type: application/octet-stream
Size: 99138 bytes
Desc: not available
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160127/d1a6afc5/attachment.obj>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160127/d1a6afc5/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: id-identifier-name-no-first-arg-label.patch
Type: application/octet-stream
Size: 103120 bytes
Desc: not available
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160127/d1a6afc5/attachment-0001.obj>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160127/d1a6afc5/attachment-0002.html>