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

Wed Jan 27 15:30:18 CST 2016

> On Jan 27, 2016, at 2:09 AM, Radosław Pietruszewski <radexpl at gmail.com> wrote:
> 
> This is great! Thank you Doug for taking a look at this.
> 
> This is a huge patch, so I haven’t looked through it all, but a few interesting bits:
> 
>> -  func finishWritingWithCompletionHandler(handler: () -> Void)
>> +  func finishWriting(completionHandler handler: () -> Void)
> 
> This is something I mentioned in my review of SE-0023. An example with a completionHandler param was made in the Guidelines (that should have an explicit label because it has a default value), and I argued that it would make sense for the “completionHandler” to have a label _even if it didn’t have a default value_. A few examples in the diff seem to confirm this notion for me.

Ah, good point. “WithCompletionHandler” is a well-followed convention, so I’d expect to see more

> 
>> -  func respondWith(data: Data)
>> +  func respond(data data: Data)
> 
> This one is unusual. I don’t mind `respond(data: …)`, but generally there’s a word to the right of “with”, and here the “with” was just to imply the argument without naming it.

The original ObjC method name was “respondWithData:”. “Data” restates type info, so SE-0023 stripped it off; this transformation makes it the first argument label.
> 
>> -  class func instantiateWith(audioComponentDescription: AudioComponentDescription, options: AudioComponentInstantiationOptions = [], completionHandler: (AVAudioUnit?, Error?) -> Void)
>> +  class func instantiate(componentDescription audioComponentDescription: AudioComponentDescription, options: AudioComponentInstantiationOptions = [], completionHandler: (AVAudioUnit?, Error?) -> Void)
> 
> Another unusual one. I don’t know AV* APIs, but for whatever reason they have an “instantiate” class method instead of just init. But just like with init the first param name is moved from the “initWithFoo” name to an label, here it also seems to make a lot of sense.

Note that the instantiated audio unit is provided to a completion handler, so this can’t be an initializer.
>> -  func indexOfItemWithTitle(title: String) -> Int
>> -  func indexOfItemWithTag(tag: Int) -> Int
>> -  func indexOfItemWithRepresentedObject(obj: AnyObject?) -> Int
>> -  func indexOfItemWithTarget(target: AnyObject?, andAction actionSelector: Selector) -> Int
>> +  func indexOfItem(title title: String) -> Int
>> +  func indexOfItem(tag tag: Int) -> Int
>> +  func indexOfItem(representedObject obj: AnyObject?) -> Int
>> +  func indexOfItem(target target: AnyObject?, andAction actionSelector: Selector) -> Int
> 
> An example of a method family that does the same fundamental job but takes different parameters. To me, it makes a ton of sense that they have the same name and then overload it by parameters. You couldn’t do that in ObjC, but I suppose that’s how a Swift-first API would be designed. But if you do that, it’s good for readability to have the first parameter explicitly described.

Thanks for the feedback!

	- Doug

> — Radek
> 
>> On 27 Jan 2016, at 08:50, Douglas Gregor <dgregor at apple.com <mailto:dgregor at apple.com>> wrote:
>> 
>>> 
>>> On Jan 25, 2016, at 6:55 AM, Radosław Pietruszewski <radexpl at gmail.com <mailto:radexpl at gmail.com>> wrote:
>>> 
>>> Hello all,
>>> 
>>> I’m overwhelmingly *for* this proposal. I think removing needless verbosity and keeping the signal-to-noise ratio high is one of the most immediately appealing aspects of Swift, as well as a great general improvement to the programming experience.
>>> 
>>> And so unswiftified (yes, it’s a word now) APIs from Objective-C stick out like a sore thumb. Not only are they harder to read and write, they visually overwhelm the less verbose, information-dense Swift-first code.
>>> 
>>> Just like previous 1.0—2.0 attempts at bridging the gap (with NSError params being translated to Swift errors, factory methods translated to initializers, etc.), automating this will be an error-prone process, and almost bound to be a bit annoying at first, before all the glitches and poor translations are smoothed out. And yet I feel like just like the previous automated translations were overwhelmingly a great thing, so will the result of this proposal.
>>> 
>>> * * *
>>> 
>>>>    Add First Argument Labels
>>>>    
>>>>    - func enumerateObjectsWith(_: NSEnumerationOptions = [], using: (AnyObject, UnsafeMutablePointer) -> Void)
>>>>    + func enumerateObjects(options _: NSEnumerationOptions = [], using: (AnyObject, UnsafeMutablePointer) -> Void)
>>> 
>>> Good! The Guidelines recommend an explicit first parameter label for arguments with a default value, but this is a good change also for another reason, a use case not included in the Guidelines (I have more to say about this in the SE-0023 thread):
>>> 
>>> “Options” is the description of the parameter, not the method itself. Even if (for whatever reason!) `options` didn’t have a default value and the word “Options” wasn’t omitted in the translation,
>>> 
>>>    enumerateObjects(options: …)
>>> 
>>> would be clearer than
>>> 
>>>    enumerateObjectsWithOptions(…)
>>> 
>>> It’s not even about the extra word, about the four useless characters, it’s simply that “WithOptions” doesn’t describe the operation at all. It’s a word that conveys no information (“with”), and “options”, which describes the first parameter. In Objective-C, there’s no such thing as parameter labels, it’s all one name, so “With” is used as a separator. But in Swift, making the first parameter’s label explicit just makes more sense.
>> 
>> That’s an interesting thought! If “with” is truly used as a convention for separating the description of the operation from the description of the first parameter, that’s something that can be codified in the Clang importer. I was curious, so I hacked it up. Here’s a diff of the Cocoa APIs that shows what things would look like if we treated “with” as a separator:
>> 
>> 	https://github.com/apple/swift-3-api-guidelines-review/pull/5/files <https://github.com/apple/swift-3-api-guidelines-review/pull/5/files>
>> 
>> It’s a diff against SE-0005, and it introduces a significant number of first argument labels. Indeed, you’ll need to grab the patch to see them all:
>> 
>> 	https://github.com/apple/swift-3-api-guidelines-review/pull/5.patch <https://github.com/apple/swift-3-api-guidelines-review/pull/5.patch>
>> 
>> A brief survey shows that some cases seem to be lining up with the guideline proposals that have been under discussion. For example, the patch includes:
>> 
>> -  func fillWith(blendMode: CGBlendMode, alpha: CGFloat)
>> -  func strokeWith(blendMode: CGBlendMode, alpha: CGFloat)
>> +  func fill(blendMode blendMode: CGBlendMode, alpha: CGFloat)
>> +  func stroke(blendMode blendMode: CGBlendMode, alpha: CGFloat)
>> 
>> -  func encodeWith(aCoder: Coder)
>> +  func encode(coder aCoder: Coder)
>> 
>> which you might recognize, because it’s the example you used:
>> 
>>> And with that in mind, I object to these translations:
>>> 
>>>    func fillWith(_: CGBlendMode, alpha: CGFloat)
>>>    func strokeWith(_: CGBlendMode, alpha: CGFloat)
>>>    func encodeWith(_: Coder)
>>> 
>>> Even though these don’t have default values, I believe this version to be clearer and make more sense, even if slightly more verbose:
>>> 
>>>    func fill(blendMode: CGBlendMode, alpha: CGFloat)
>>>    func stroke(blendMode: CGBlendMode, alpha: CGFloat)
>>>    func encode(coder: Coder)
>> 
>> Another random interesting example I encountered:
>> 
>> -  func addArcWithCenter(center: CGPoint, radius: CGFloat, startAngle: CGFloat, endAngle: CGFloat, clockwise: Bool)
>> +  func addArc(center center: CGPoint, radius: CGFloat, startAngle: CGFloat, endAngle: CGFloat, clockwise: Bool)
>> 
>> which seems to match the idea behind Erica’s "semantic relationship between the parameters is stronger than their relation to the operation” (or Paul Cantrell’s similar notion of "the direct object is several args taken together”, which feels more in line with the way the API guidelines are written).
>> 
>> There’s also this:
>> 
>> -  func tracksWithMediaType(mediaType: String) -> [AVMovieTrack]
>> +  func tracks(mediaType mediaType: String) -> [AVMovieTrack]
>> 
>> -  func tracksWithMediaCharacteristic(mediaCharacteristic: String) ->
>> +  func tracks(mediaCharacteristic mediaCharacteristic: String) -> [AVMovieTrack]
>> 
>> which feels reminiscent of Paul’s “resource” example:
>> 
>>     service.resource("/foo")
>>     service.resource(absoluteURL: "http://bar.com <http://bar.com/>")
>>     service.resource(absoluteURL: NSURL(string: "http://bar.com <http://bar.com/>"))
>> 
>> where (I think) the argument is that the various methods should all have the same base name because they’re all returning “tracks” or a “resource”, respectively.
>> 
>> There is a ton of data in that patch. I’d be interested to hear whether the resulting Cocoa APIs feel better in Swift—are they following the evolving set of guidelines for first argument labels that are under discussion, and are the resulting APIs clearer/more Swifty? What specific APIs work well and where does this “with-as-separator” heuristic break down?
>> 
>> 	- Doug
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160127/049523a3/attachment.html>