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

[Dave Abrahams]

on Wed Jan 27 2016, Douglas Gregor <dgregor-AT-apple.com> wrote:

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

The second; it's AWESOME!

-- 
-Dave