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

[Radosław Pietruszewski]

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.

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)

Again, the method, the action itself (“fill”, “stroke”, “encode”) doesn’t naturally describe the first parameter in a way “insert” on a collection, or “addObserver” would. The blend mode and coder values here are merely _options_ of the method, not its _fundamental job_.

One way to conceptualize the difference is to think of arguments as being either “inputs” or “options”. A passed element to be inserted to a collection is an input, but blend mode is only an option of a fill, an operation that conceptually takes no inputs.

(I also don’t believe that “don’t repeat type information” rule applies here. “blend mode” is a description of the parameter, not only its type. Same with coder. We’re not needlessly repeating type information here, we’re describing option parameters, which happen to be the same as type names.)

* * *

> 	• How much effort did you put into your review? A glance, a quick reading, or an in-depth study?

I’ve read the whole proposal, as well as the related proposals, and read the thread for this review.

> 	• If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?

Not other languages as far as I remember, but Swift has a precedent for similar-ish automatic translations of ObjC APIs and they were, on the whole, good.

> 	• Is the problem being addressed significant enough to warrant a change to Swift?
> 	• Does this proposal fit well with the feel and direction of Swift?

Yes, and oh gosh yes.

Thanks,
— Radek

> On 22 Jan 2016, at 22:02, Douglas Gregor via swift-evolution <swift-evolution at swift.org> wrote:
> 
> Hello Swift community,
> 
> The review of SE-0005"Better Translation of Objective-C APIs Into Swift" begins now and runs through January 31, 2016. The proposal is available here:
> 
> https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md <https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md>
> Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at
> 
> https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>
> or, if you would like to keep your feedback private, directly to the review manager. When replying, please try to keep the proposal link at the top of the message:
> 
> Proposal link:
> 
> https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md <https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md>
> Reply text
> 
> Other replies
>  <https://github.com/apple/swift-evolution#what-goes-into-a-review-1>What goes into a review?
> 
> The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of Swift. When writing your review, here are some questions you might want to answer in your review:
> 
> What is your evaluation of the proposal?
> Is the problem being addressed significant enough to warrant a change to Swift?
> Does this proposal fit well with the feel and direction of Swift?
> If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
> How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
> More information about the Swift evolution process is available at
> 
> https://github.com/apple/swift-evolution/blob/master/process.md <https://github.com/apple/swift-evolution/blob/master/process.md>
> Thank you,
> 
> -Doug Gregor
> 
> Review Manager
> 
> _______________________________________________
> 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/20160125/83bd72b3/attachment.html>