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


(Douglas Gregor) #1

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
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
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
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
Thank you,

-Doug Gregor

Review Manager


(Jacob Bandes-Storch) #2

Proposal link:
https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md

What is your evaluation of the proposal?

I would really appreciate seeing what *all* of the Foundation/Cocoa/Cocoa
Touch APIs would look like when imported using this scheme. If we're going
to bikeshed API translation, we should bikeshed all of it to avoid
inconsistency. (It may be that some issues aren't resolvable with the
simple rules proposed, and instead we should improve the API overlays.)

Some specific concerns:

     func *reversing()* -> UIBezierPath

I believe this would be better named *reversed()*.

    var *dateComponentUndefined*: Int { get }

It seems pretty weird to have a global/top-level constant that starts with
a lowercase letter, and whose first 2 subwords are describing its type.

    class func *darkGray*() -> UIColor

I would rather see this imported as `class var *DarkGray*: UIColor { get }`.

Otherwise, I'm okay with the proposed changes. I really like the "Add
Default Arguments" section. :slight_smile:

Is the problem being addressed significant enough to warrant a change to

Swift?

Yes. The (current) majority of Swift users are writing software for Apple
platforms, so they interact constantly with Obj-C APIs such as these.

How much effort did you put into your review? A glance, a quick reading,

or an in-depth study?

Fairly in-depth.

Jacob

···

On Fri, Jan 22, 2016 at 1:02 PM, Douglas Gregor via swift-evolution < swift-evolution@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

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

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

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

Thank you,

-Doug Gregor

Review Manager

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(plx) #3

My main reaction is the proposed translation is usually an improvement, but the proposal as-written is a bit hand-wavy on how to handle the situations where it doesn’t do a good job.

What I mean is, it is written from a perspective that comes across as “we have a solid-enough understanding of what Swift-y APIs should look like, and this proposal is sketching an automated approach to map Objective-C into that as best as possible; of course, in some cases the automated approach will be insufficient, and in those cases explicit annotations will be called for”.

But, as came up on the API guidelines discussion, there are parts of Objective-C for which there doesn’t seem to be any commonly-agreed-upon “Swift-y” equivalent; the delegate-style APIs are one such obvious case (and my motivating example), but there may be others once the enhanced translation starts seeing real use.

For such “problematic API styles” it’s not really going to be enough to say, for example, “we’ll add explicit annotations to deal with those”, because *what* those annotations *should be* doesn’t seem all that obvious right now; at least for the delegate-style APIs, even the enhanced translations are still wildly out of sync with the Swift API guidelines, and that style will either need to be grandfathered-in or some other form agreed-upon.

To make it concrete, here’s a few from the `UICollectionView*` family:

// IMHO an annoying inconsistency in how the type is incorporated into the 2nd argument’s label:
func collectionView(collectionView: UICollectionView, didEndDisplaying cell: UICollectionViewCell, forItemAt indexPath: IndexPath)
func collectionView(collectionView: UICollectionView, didEndDisplayingSupplementaryView view: UICollectionReusableView, forElementOfKind elementKind: String, at indexPath: IndexPath)

// IMHO an annoying inconsistency between the 2nd and 3rd argument labels:
func collectionView(collectionView: UICollectionView, targetIndexPathForMoveFromItemAt originalIndexPath: IndexPath, toProposedIndexPath proposedIndexPath: IndexPath) -> IndexPath

// IMHO an annoying inconsistency vis-a-vis its 2nd and 3rd argument labels and those from the previous example:
func collectionView(collectionView: UICollectionView, moveItemAt sourceIndexPath: IndexPath, to destinationIndexPath: IndexPath)

…which I’d summarize by first reiterating that these are both:

- nowhere near in accord with the Swift API guidelines
- worse-off for being “partially translated” (the original APIs are verbose but predictable-and-mutually-consistent; these are verbose and neither predictable nor mutually-consistent)

I’m not sure what the right approach for the delegate APIs is — maybe they get grandfathered-in, maybe some Swift-ier form is chosen for them — but I think their presence shows a weakness of the *proposal* at this time: there are API territories for which there is as-yet no agreed-upon ideal translation to some Swift-ier form, and some more-explicit mention of such scenarios seems like it ought to go in the proposal (even if just in the future-steps section).

That’s my 2c at this time

···

On Jan 22, 2016, at 3:02 PM, Douglas Gregor via swift-evolution <swift-evolution@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
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
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
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
Thank you,

-Doug Gregor

Review Manager

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Radek Pietruszewski) #4

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@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
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
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
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
Thank you,

-Doug Gregor

Review Manager

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Brent Royal-Gordon) #5

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:

Specific comments:

  • When the Objective-C type is a block, the type name is "Block."

I think we should also consider "Handler" to be a type name for a block. The word appears in many Cocoa APIs, and it basically just means "probably-escaping block". Moreover, it's applied *inconsistently*; for instance, older APIs often say "completionHandler" where more recent APIs say "completion". I don't believe it carries much additional meaning and trimming it would improve API consistency.

extension UIViewController {
  func dismissAnimated(flag: Bool, completion: (() -> Void)? = nil)
}

I believe this should be translated as `dismiss(animated flag: Bool, completion: (() -> Void)? = nil)`. (Note the label on the first argument.) This pattern appears throughout the UI frameworks, particularly UIKit, and it always means exactly the same thing. Whether or not the operation is animated is fundamentally an option on the method, not a fundamental aspect of the operation. Though we don't supply a default for it, and I don't suggest we ought to, we very reasonably could.

I don't think there's a very large rule here—just `fooAnimated(_: Bool)` should be `foo(animated: Bool)`.

  • What is your evaluation of the proposal?

Overall, I think this dramatically improves most Cocoa APIs. +1.

  • Is the problem being addressed significant enough to warrant a change to Swift?

Yes.

  • Does this proposal fit well with the feel and direction of Swift?

Yes, particularly with the introduction of the API Guidelines.

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

Well, I've tried using RubyCocoa and its ilk; does that count? This is way better than any of that stuff.

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

I'd say a quick reading, plus a read-through of the API Guidelines thread and this thread.

···

--
Brent Royal-Gordon
Architechies


(Drew Crawford) #6

I am in favor of this proposal on balance, and I leave the bulk of this to people who interop with Objective-C more often than I do.

I would like to confine my remarks to one corner where I think we are making a very serious mistake.

The removal of the "NS" prefix for the Foundation module (or other specifically identified modules) is a mechanical translation for all global symbols defined within that module that can be performed in the Clang importer.

As I understand it (and I am no Cocoa historian) the NS prefix was originally introduced because Objective-C lacks namespacing.

The thinking seems to be that since Swift has proper namespacing, this historicism is no longer necessary. I find this argument very flimsy.

Of course Swift has stronger namespacing if one's frame of reference is Objective-C or C. But for those of us coming from other language backgrounds, namespacing means something much stronger than Swift's concept of it. I don't mean to suggest that Swift's design is wrong exactly (less is sometimes more), but I do mean to say that if we propose to undo a decision that worked for several decades and break every Swift project in existence on the theory that Swift's namespacing is strong enough we had better be right.

For those unfamiliar, I will explain some of the namespacing tools Swift lacks relative to other languages. First, many languages have a "hierarchical" namespace system, where one can say

import Foundation.Net.URL
let s = Session(...)

instead of for example

import Foundation
let s = NSURLSession(...)

Some form of this is used in Rust, Python, and C#, as far as I know. I believe Swift has some counterfeit version of this, as the book mentions you can import a "submodule <https://developer.apple.com/library/ios/documentation/Swift/Conceptual/Swift_Programming_Language/Declarations.html#//apple_ref/swift/grammar/import-declaration>", but I do not know what that is, do not know how to make one, have never seen anyone use one, the book suggests it goes only 2 levels deep, and perhaps as a consequences of some of these problems nobody thought of using this for Foundation.

A closely related difference is the use of so-called "selective" imports, where we import only a single symbol (or a list of explicitly-identified symbols) into the scope. We might express this as

from Foundation.Net.URL import Session, HTTP //import two classes only
let s = Session(...)

Again I think Swift technically supports some way to avoid importing a whole gigantic namespace like Foundation, but I am not aware of any actual uses of this feature, and certainly the convention is not to write code this way. Meanwhile, let's check in with the Python community, who standardized the following guidance on these "wildcard" imports as part of their language evolution process:

Wildcard imports ( from <module> import * ) should be avoided, as they make it unclear which names are present in the namespace, confusing both readers and many automated tools. There is one defensible use case for a wildcard import...

When a language has a robust namespacing system, which we do not, there are many follow-on consequences. One is that an import statement is much more of a scalpel than a bludgeon; each import statement only introduces a handful of new names (even if it is a so-called "wildcard" import that grabs all children of some namespace, most of those children are themselves namespaces), unlike importing Foundation which contains thousands of direct child types that are injected into the local scope.

Another consequence is that class names become quite short, shadow each other, and nobody bats an eye. I searched the C# standard library for "Session", and found some 12 classes with that name:

These "standard library" classes not only potentially shadow programmer-defined types, they also shadow each other. But because the C# language has a robust namespacing system, the chances of there being more than one thing called "Session" in scope in your program (or for that matter, when developing the standard library itself) is quite small, so it's a non-issue.

Now we return to the question of dropping the NS prefix, which will rename thousands of classes in a typical program that has `import Foundation`, in a way that potentially (let's be honest. More like "probably") shadows one or more programmer-defined classes. Our review criteria is:

Is the problem being addressed significant enough to warrant a change to Swift?

No, the elimination of 2 characters is not significant enough of a problem to break all Swift programs, let alone to introduce literally thousands of new opportunities for shadowing.

To its credit, the proposal acknowledges this, and offers a concession:

Note that this removal can create conflicts with the standard library. For example, NSString and NSArray will become String and Array, respectively, and Foundation's versions will shadow the standard library's versions. In cases where the Swift 3 names of standard library entities conflict with prefix-stripped Foundation entities, we retain the NS prefix. These Foundation entities are: NSArray, NSDictionary, NSInteger, NSRange, NSSet, and NSString.

But of course this needlessly draws a distinction between NSString et al and the "normal" Foundation types, and what's more it draws that distinction based on the present composition of the Swift standard library and the present composition of Foundation. But we have already decided not to guarantee the source compatibility of the standard library, so what happens when that composition changes? Will we then go back and tweak which classes get NS prefixed to them again?

In my view, if Swift's namespacing is not good enough to let us drop the NS in NSString it is not good enough to drop any prefix. If we believe that a programmer will struggle to distinguish between Swift String and Foundation String then we should expect them to struggle for any two classes in any two frameworks, and this is special pleading on the part of Foundation. C#'s libraries declare *twelve* different `Session`s and nobody bats an eye, but we have two types share a name and everybody loses their minds? Our namespacing is not good enough to kill the prefix, period.

We should either drop these prefixes or we should not; because the claimed motivation–that we have "good enough" namespacing in the language now–is either true or it is not. This proposal admits that it is not, and tries to drop the prefixes anyway. I believe that is a mistake.

I certainly support the goal of eliminating these prefixes, they are ugly, they need to be killed, and namespacing is the right solution. But we must not jump out of the plane until we are very sure our parachute is in order. In Swift 3 it is not.

I do think the bulk of the proposal is fine, and I apologize for using quite stark language for such a small paragraph in an otherwise reasonable proposal, but I think the problem buried in here is quite serious and is being overlooked.

Drew

···

On Jan 22, 2016, at 3:02 PM, Douglas Gregor via swift-evolution <swift-evolution@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
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
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
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
Thank you,

-Doug Gregor

Review Manager

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Dave Abrahams) #7

That information is all right here, under Platforms:

  https://github.com/apple/swift-3-api-guidelines-review/tree/swift-3

HTH,

···

on Sat Jan 23 2016, Jacob Bandes-Storch <swift-evolution@swift.org> wrote:

Proposal link:
https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md

What is your evaluation of the proposal?

I would really appreciate seeing what *all* of the Foundation/Cocoa/Cocoa
Touch APIs would look like when imported using this scheme. If we're going
to bikeshed API translation, we should bikeshed all of it to avoid
inconsistency. (It may be that some issues aren't resolvable with the
simple rules proposed, and instead we should improve the API
overlays.)

--
-Dave


(Douglas Gregor) #8

I’ll come back to the rest laster, but we’ve provided this at

  https://github.com/apple/swift-3-api-guidelines-review/compare/swift-2...swift-3

  - Doug

···

On Jan 23, 2016, at 12:59 AM, Jacob Bandes-Storch <jtbandes@gmail.com> wrote:

Proposal link:
https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md

> What is your evaluation of the proposal?

I would really appreciate seeing what all of the Foundation/Cocoa/Cocoa Touch APIs would look like when imported using this scheme. If we're going to bikeshed API translation, we should bikeshed all of it to avoid inconsistency. (It may be that some issues aren't resolvable with the simple rules proposed, and instead we should improve the API overlays.)


(Tim Hawkins) #9

Is the proposal going to improve support for "c" function import too, or is
it limited to objective-c?

Im asking because there are currently some weaknesses in importing libs
like glibc etc on linux, like the lack of support for functions with
varadic arguments, ie ioctrl etc. Which requires any interfaces to said
functions to have "c" wrappers built for them, before they can be imported.

···

On Jan 24, 2016 9:42 PM, "plx via swift-evolution" < swift-evolution@swift.org> wrote:

My main reaction is the proposed translation is usually an improvement,
but the proposal as-written is a bit hand-wavy on how to handle the
situations where it doesn’t do a good job.

What I mean is, it is written from a perspective that comes across as “we
have a solid-enough understanding of what Swift-y APIs should look like,
and this proposal is sketching an automated approach to map Objective-C
into that as best as possible; of course, in some cases the automated
approach will be insufficient, and in those cases explicit annotations will
be called for”.

But, as came up on the API guidelines discussion, there are parts of
Objective-C for which there doesn’t seem to be any commonly-agreed-upon
“Swift-y” equivalent; the delegate-style APIs are one such obvious case
(and my motivating example), but there may be others once the enhanced
translation starts seeing real use.

For such “problematic API styles” it’s not really going to be enough to
say, for example, “we’ll add explicit annotations to deal with those”,
because *what* those annotations *should be* doesn’t seem all that obvious
right now; at least for the delegate-style APIs, even the enhanced
translations are still wildly out of sync with the Swift API guidelines,
and that style will either need to be grandfathered-in or some other form
agreed-upon.

To make it concrete, here’s a few from the `UICollectionView*` family:

// IMHO an annoying inconsistency in how the type is incorporated into the
2nd argument’s label:
func collectionView(collectionView: UICollectionView,
didEndDisplaying cell: UICollectionViewCell, forItemAt indexPath: IndexPath)
func collectionView(collectionView: UICollectionView,
didEndDisplayingSupplementaryView view: UICollectionReusableView,
forElementOfKind elementKind: String, at indexPath: IndexPath)

// IMHO an annoying inconsistency between the 2nd and 3rd argument labels:
func collectionView(collectionView: UICollectionView,
targetIndexPathForMoveFromItemAt originalIndexPath: IndexPath,
toProposedIndexPath proposedIndexPath: IndexPath) -> IndexPath

// IMHO an annoying inconsistency vis-a-vis its 2nd and 3rd argument
labels and those from the previous example:
func collectionView(collectionView: UICollectionView,
moveItemAt sourceIndexPath: IndexPath, to destinationIndexPath: IndexPath)

…which I’d summarize by first reiterating that these are both:

- nowhere near in accord with the Swift API guidelines
- worse-off for being “partially translated” (the original APIs are
verbose but predictable-and-mutually-consistent; these are verbose and
neither predictable nor mutually-consistent)

I’m not sure what the right approach for the delegate APIs is — maybe they
get grandfathered-in, maybe some Swift-ier form is chosen for them — but I
think their presence shows a weakness of the *proposal* at this time: there
are API territories for which there is as-yet no agreed-upon ideal
translation to some Swift-ier form, and some more-explicit mention of such
scenarios seems like it ought to go in the proposal (even if just in the
future-steps section).

That’s my 2c at this time

On Jan 22, 2016, at 3:02 PM, Douglas Gregor via swift-evolution < > swift-evolution@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

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

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

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

Thank you,

-Doug Gregor

Review Manager
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Dave Abrahams) #10

Thanks for your review, Jacob—

Proposal link:
https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md

What is your evaluation of the proposal?

I would really appreciate seeing what *all* of the Foundation/Cocoa/Cocoa
Touch APIs would look like when imported using this scheme. If we're going
to bikeshed API translation, we should bikeshed all of it to avoid
inconsistency. (It may be that some issues aren't resolvable with the
simple rules proposed, and instead we should improve the API overlays.)

Some specific concerns:

     func *reversing()* -> UIBezierPath

I believe this would be better named *reversed()*.

It certainly would. I wonder if it's possible for us to tune the
heuristics accordingly, and how many other places that might fix. My
research tells me this is a one-off problem that probably should be
handled “on a per-API basis via annotation within the Objective-C
headers”
(c.f. https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md#proposed-solution)

  $ git grep -nHE -e 'func [a-z]*ing\>\(\)' | grep -v 'string()'
  ../../Platforms/OSX/DiscRecording.swift:678: func encoding() -> UInt
  ../../Platforms/OSX/Quartz.swift:1822: func mirroring() -> Bool
  ../../Platforms/OSX/SceneKit.swift:4762: class func spring() -> SCNPhysicsField
  ../../Platforms/OSX/WebKit.swift:340: func padding() -> String!
  ../../Platforms/iOS/SceneKit.swift:4474: class func spring() -> SCNPhysicsField
  ../../Platforms/iOS/UIKit.swift:2237: func reversing() -> UIBezierPath
  ../../Platforms/tvOS/SceneKit.swift:4474: class func spring() -> SCNPhysicsField
  ../../Platforms/tvOS/UIKit.swift:1723: func reversing() -> UIBezierPath
  ../../Platforms/watchOS/UIKit.swift:424: func reversing() -> UIBezierPath

Except for reversing, these are all fine AFAICT.

    var *dateComponentUndefined*: Int { get }

It seems pretty weird to have a global/top-level constant that starts with
a lowercase letter,

I get that. Starting with lowercase is in conformance with the
guidelines as written, FWIW.

and whose first 2 subwords are describing its type.

That's compensating for weak type information.

    class func *darkGray*() -> UIColor

I would rather see this imported as `class var *DarkGray*: UIColor { get }`.

Why should we capitalize some vars and not others?

···

on Sat Jan 23 2016, Jacob Bandes-Storch <swift-evolution@swift.org> wrote:

Otherwise, I'm okay with the proposed changes. I really like the "Add
Default Arguments" section. :slight_smile:

Is the problem being addressed significant enough to warrant a change to

Swift?

Yes. The (current) majority of Swift users are writing software for Apple
platforms, so they interact constantly with Obj-C APIs such as these.

How much effort did you put into your review? A glance, a quick reading,

or an in-depth study?

Fairly in-depth.

Jacob

On Fri, Jan 22, 2016 at 1:02 PM, Douglas Gregor via swift-evolution < > swift-evolution@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

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

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

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

Thank you,

-Doug Gregor

Review Manager

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave


(Douglas Gregor) #11

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

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

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

···

On Jan 25, 2016, at 6:55 AM, Radosław Pietruszewski <radexpl@gmail.com> wrote:


(Tony Parker) #12

Hi Drew,

I am in favor of this proposal on balance, and I leave the bulk of this to people who interop with Objective-C more often than I do.

I would like to confine my remarks to one corner where I think we are making a very serious mistake.

The removal of the "NS" prefix for the Foundation module (or other specifically identified modules) is a mechanical translation for all global symbols defined within that module that can be performed in the Clang importer.

As I understand it (and I am no Cocoa historian) the NS prefix was originally introduced because Objective-C lacks namespacing.

The thinking seems to be that since Swift has proper namespacing, this historicism is no longer necessary. I find this argument very flimsy.

Of course Swift has stronger namespacing if one's frame of reference is Objective-C or C. But for those of us coming from other language backgrounds, namespacing means something much stronger than Swift's concept of it. I don't mean to suggest that Swift's design is wrong exactly (less is sometimes more), but I do mean to say that if we propose to undo a decision that worked for several decades and break every Swift project in existence on the theory that Swift's namespacing is strong enough we had better be right.

For those unfamiliar, I will explain some of the namespacing tools Swift lacks relative to other languages. First, many languages have a "hierarchical" namespace system, where one can say

import Foundation.Net.URL
let s = Session(...)

instead of for example

import Foundation
let s = NSURLSession(...)

Some form of this is used in Rust, Python, and C#, as far as I know. I believe Swift has some counterfeit version of this, as the book mentions you can import a "submodule <https://developer.apple.com/library/ios/documentation/Swift/Conceptual/Swift_Programming_Language/Declarations.html#//apple_ref/swift/grammar/import-declaration>", but I do not know what that is, do not know how to make one, have never seen anyone use one, the book suggests it goes only 2 levels deep, and perhaps as a consequences of some of these problems nobody thought of using this for Foundation.

A closely related difference is the use of so-called "selective" imports, where we import only a single symbol (or a list of explicitly-identified symbols) into the scope. We might express this as

from Foundation.Net.URL import Session, HTTP //import two classes only
let s = Session(...)

Again I think Swift technically supports some way to avoid importing a whole gigantic namespace like Foundation, but I am not aware of any actual uses of this feature, and certainly the convention is not to write code this way. Meanwhile, let's check in with the Python community, who standardized the following guidance on these "wildcard" imports as part of their language evolution process:

Wildcard imports ( from <module> import * ) should be avoided, as they make it unclear which names are present in the namespace, confusing both readers and many automated tools. There is one defensible use case for a wildcard import...

When a language has a robust namespacing system, which we do not, there are many follow-on consequences. One is that an import statement is much more of a scalpel than a bludgeon; each import statement only introduces a handful of new names (even if it is a so-called "wildcard" import that grabs all children of some namespace, most of those children are themselves namespaces), unlike importing Foundation which contains thousands of direct child types that are injected into the local scope.

Another consequence is that class names become quite short, shadow each other, and nobody bats an eye. I searched the C# standard library for "Session", and found some 12 classes with that name:

<Screen Shot 2016-01-30 at 3.44.23 PM.png>

These "standard library" classes not only potentially shadow programmer-defined types, they also shadow each other. But because the C# language has a robust namespacing system, the chances of there being more than one thing called "Session" in scope in your program (or for that matter, when developing the standard library itself) is quite small, so it's a non-issue.

Now we return to the question of dropping the NS prefix, which will rename thousands of classes in a typical program that has `import Foundation`, in a way that potentially (let's be honest. More like "probably") shadows one or more programmer-defined classes. Our review criteria is:

Is the problem being addressed significant enough to warrant a change to Swift?

No, the elimination of 2 characters is not significant enough of a problem to break all Swift programs, let alone to introduce literally thousands of new opportunities for shadowing.

To its credit, the proposal acknowledges this, and offers a concession:

Note that this removal can create conflicts with the standard library. For example, NSString and NSArray will become String and Array, respectively, and Foundation's versions will shadow the standard library's versions. In cases where the Swift 3 names of standard library entities conflict with prefix-stripped Foundation entities, we retain the NS prefix. These Foundation entities are: NSArray, NSDictionary, NSInteger, NSRange, NSSet, and NSString.

But of course this needlessly draws a distinction between NSString et al and the "normal" Foundation types, and what's more it draws that distinction based on the present composition of the Swift standard library and the present composition of Foundation. But we have already decided not to guarantee the source compatibility of the standard library, so what happens when that composition changes? Will we then go back and tweak which classes get NS prefixed to them again?

In my view, if Swift's namespacing is not good enough to let us drop the NS in NSString it is not good enough to drop any prefix. If we believe that a programmer will struggle to distinguish between Swift String and Foundation String then we should expect them to struggle for any two classes in any two frameworks, and this is special pleading on the part of Foundation. C#'s libraries declare *twelve* different `Session`s and nobody bats an eye, but we have two types share a name and everybody loses their minds? Our namespacing is not good enough to kill the prefix, period.

I’m actually not sure how this line about shadowing ended up in the guidelines, because it is not our plan. Instead, I have always wanted to do something very close to what you suggest and rename these to something like “Dynamic.Array” to reflect its role as a dynamically-dispatched, subclass-capable Array.

Types like NSURL are intended to be the canonical URL for everyone to use, so for me it feels very natural to drop the prefix and make them as accessible as Array, String, etc.

- Tony

···

On Jan 30, 2016, at 3:01 PM, Drew Crawford via swift-evolution <swift-evolution@swift.org> wrote:

We should either drop these prefixes or we should not; because the claimed motivation–that we have "good enough" namespacing in the language now–is either true or it is not. This proposal admits that it is not, and tries to drop the prefixes anyway. I believe that is a mistake.

I certainly support the goal of eliminating these prefixes, they are ugly, they need to be killed, and namespacing is the right solution. But we must not jump out of the plane until we are very sure our parachute is in order. In Swift 3 it is not.

I do think the bulk of the proposal is fine, and I apologize for using quite stark language for such a small paragraph in an otherwise reasonable proposal, but I think the problem buried in here is quite serious and is being overlooked.

Drew

On Jan 22, 2016, at 3:02 PM, Douglas Gregor via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@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
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
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
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
Thank you,

-Doug Gregor

Review Manager

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Nate Cook) #13

This is a concurring opinion with Drew's review, agreeing that we should reconsider removing the "NS" prefix but providing my own reasons. The proposal as a whole is exciting and far-reaching, but this particular change is misguided. My objections are:

1) The change will elide the different semantic expectations for Foundation and Swift standard library types.

Prefix-less Foundation types will blur the different norms and expectations for Foundation types vs what we have in the Swift standard library, particularly in regards to value vs reference semantics of collection types.

The Swift standard library defines Array, Set, and Dictionary as collection types with value semantics that operate quite differently from their peers in Foundation. This change will introduce OrderedSet, CountedSet, HashTable, MapTable, and others, all of which use reference semantics and therefore don't provide the same set of guarantees about ownership and immutability.

As an example, the seemingly similar Set and CountedSet types produce different results from nearly identical code. Swift's Set type has value semantics, so changes to a copy don't affect the original Set instance:

let simpleSet = Set(["one", "two", "three"])
var copiedSimpleSet = simpleSet
copiedSimpleSet.remove("one")

copiedSimpleSet.contains("one") // false
simpleSet.contains("one") // true

CountedSet (née NSCountedSet), on the other hand, uses reference semantics, so changes to a copy of an instance. This is true whether the copy is an explicit one made via assignment or the implicit copy made when calling a function with CountedSet as a parameter. This example shows how nearly code nearly identical to the above produces very different results:

let countedSet = CountedSet(array: ["one", "two", "three"])
var copiedCountedSet = countedSet
copiedCountedSet.remove("one")

copiedCountedSet.contains("one") // false
countedSet.contains("one") // false!

Collections constructed from immutable/mutable class clusters (like OrderedSet and MutableOrderedSet) pose the same problems, since you may be using a mutable instance of the "immutable" collection. We clearly are already dealing with this difference today, but eliminating the "NS" prefix implies that Foundation types are on the same level as the standard library. This makes the confusion more pronounced and significantly increases both the learning curve of the Swift & Foundation APIs and the risk of errors when using different collection types.

2) The change may stifle the development of more Swift-oriented APIs.

Foundation types were developed in and for a language that uses reference semantics and subclassing, rather than value semantics and a protocol-oriented approach. The designs therefore use and reinforce norms that relate better to Objective-C than to Swift—class clusters of non-final, immutable types with mutable subclasses, immutable types with separate but related mutable counterparts, etc.

A Swift-native CountedSet (and other collections) would surely have value semantics built in. What about other types—do the new Calendar/Date/DateComponents types look like the system that we would design from the ground up in Swift? How about URL and URLComponents? Dropping the "NS" prefix would make it more difficult to gradually expand the standard library to encompass bridging versions of these and other common types.

3) The change will make it harder to find information about the revised APIs.

Excellent search-ability is an unintended benefit of the "NS" prefix, and can be understood as a way that these types avoid collisions in the vast namespace-less sea of Internet search results. Searching for help with URL and Calendar will be much more difficult than their NS'ed counterparts.

Especially given the challenges that this proposal will pose for code sourced from tutorials, blog posts, Stack Overflow answers, etc., keeping at least the class names as sign posts seems valuable.

4) We'll still be using prefixes after the change.

While the removal of "NS" is far-reaching, prefixes will still be a common occurrence in code written in Swift. UIKit and AppKit, along with all the various frameworks, will still retain their prefixes, so removing prefixes in the case of Foundation types will be more the exception than the norm. As such, any benefit of the removal would be mitigated by the continued use of prefixes for the rest of the first-party types we rely on.

In sum, the change would make the language and its APIs more confusing and more difficult to use today, would make it more difficult to migrate to modern designs in the future, and would ultimately provide a very minor benefit. I encourage the Swift core team to reconsider the "Strip the "NS" prefix from Foundation APIs" portion of the proposal.

Nate

···

On Jan 30, 2016, at 5:01 PM, Drew Crawford via swift-evolution <swift-evolution@swift.org> wrote:

I am in favor of this proposal on balance, and I leave the bulk of this to people who interop with Objective-C more often than I do.

I would like to confine my remarks to one corner where I think we are making a very serious mistake.

The removal of the "NS" prefix for the Foundation module (or other specifically identified modules) is a mechanical translation for all global symbols defined within that module that can be performed in the Clang importer.

As I understand it (and I am no Cocoa historian) the NS prefix was originally introduced because Objective-C lacks namespacing.

The thinking seems to be that since Swift has proper namespacing, this historicism is no longer necessary. I find this argument very flimsy.

Of course Swift has stronger namespacing if one's frame of reference is Objective-C or C. But for those of us coming from other language backgrounds, namespacing means something much stronger than Swift's concept of it. I don't mean to suggest that Swift's design is wrong exactly (less is sometimes more), but I do mean to say that if we propose to undo a decision that worked for several decades and break every Swift project in existence on the theory that Swift's namespacing is strong enough we had better be right.

For those unfamiliar, I will explain some of the namespacing tools Swift lacks relative to other languages. First, many languages have a "hierarchical" namespace system, where one can say

import Foundation.Net.URL
let s = Session(...)

instead of for example

import Foundation
let s = NSURLSession(...)

Some form of this is used in Rust, Python, and C#, as far as I know. I believe Swift has some counterfeit version of this, as the book mentions you can import a "submodule <https://developer.apple.com/library/ios/documentation/Swift/Conceptual/Swift_Programming_Language/Declarations.html#//apple_ref/swift/grammar/import-declaration>", but I do not know what that is, do not know how to make one, have never seen anyone use one, the book suggests it goes only 2 levels deep, and perhaps as a consequences of some of these problems nobody thought of using this for Foundation.

A closely related difference is the use of so-called "selective" imports, where we import only a single symbol (or a list of explicitly-identified symbols) into the scope. We might express this as

from Foundation.Net.URL import Session, HTTP //import two classes only
let s = Session(...)

Again I think Swift technically supports some way to avoid importing a whole gigantic namespace like Foundation, but I am not aware of any actual uses of this feature, and certainly the convention is not to write code this way. Meanwhile, let's check in with the Python community, who standardized the following guidance on these "wildcard" imports as part of their language evolution process:

Wildcard imports ( from <module> import * ) should be avoided, as they make it unclear which names are present in the namespace, confusing both readers and many automated tools. There is one defensible use case for a wildcard import...

When a language has a robust namespacing system, which we do not, there are many follow-on consequences. One is that an import statement is much more of a scalpel than a bludgeon; each import statement only introduces a handful of new names (even if it is a so-called "wildcard" import that grabs all children of some namespace, most of those children are themselves namespaces), unlike importing Foundation which contains thousands of direct child types that are injected into the local scope.

Another consequence is that class names become quite short, shadow each other, and nobody bats an eye. I searched the C# standard library for "Session", and found some 12 classes with that name:

<Screen Shot 2016-01-30 at 3.44.23 PM.png>

These "standard library" classes not only potentially shadow programmer-defined types, they also shadow each other. But because the C# language has a robust namespacing system, the chances of there being more than one thing called "Session" in scope in your program (or for that matter, when developing the standard library itself) is quite small, so it's a non-issue.

Now we return to the question of dropping the NS prefix, which will rename thousands of classes in a typical program that has `import Foundation`, in a way that potentially (let's be honest. More like "probably") shadows one or more programmer-defined classes. Our review criteria is:

Is the problem being addressed significant enough to warrant a change to Swift?

No, the elimination of 2 characters is not significant enough of a problem to break all Swift programs, let alone to introduce literally thousands of new opportunities for shadowing.

To its credit, the proposal acknowledges this, and offers a concession:

Note that this removal can create conflicts with the standard library. For example, NSString and NSArray will become String and Array, respectively, and Foundation's versions will shadow the standard library's versions. In cases where the Swift 3 names of standard library entities conflict with prefix-stripped Foundation entities, we retain the NS prefix. These Foundation entities are: NSArray, NSDictionary, NSInteger, NSRange, NSSet, and NSString.

But of course this needlessly draws a distinction between NSString et al and the "normal" Foundation types, and what's more it draws that distinction based on the present composition of the Swift standard library and the present composition of Foundation. But we have already decided not to guarantee the source compatibility of the standard library, so what happens when that composition changes? Will we then go back and tweak which classes get NS prefixed to them again?

In my view, if Swift's namespacing is not good enough to let us drop the NS in NSString it is not good enough to drop any prefix. If we believe that a programmer will struggle to distinguish between Swift String and Foundation String then we should expect them to struggle for any two classes in any two frameworks, and this is special pleading on the part of Foundation. C#'s libraries declare *twelve* different `Session`s and nobody bats an eye, but we have two types share a name and everybody loses their minds? Our namespacing is not good enough to kill the prefix, period.

We should either drop these prefixes or we should not; because the claimed motivation–that we have "good enough" namespacing in the language now–is either true or it is not. This proposal admits that it is not, and tries to drop the prefixes anyway. I believe that is a mistake.

I certainly support the goal of eliminating these prefixes, they are ugly, they need to be killed, and namespacing is the right solution. But we must not jump out of the plane until we are very sure our parachute is in order. In Swift 3 it is not.

I do think the bulk of the proposal is fine, and I apologize for using quite stark language for such a small paragraph in an otherwise reasonable proposal, but I think the problem buried in here is quite serious and is being overlooked.

Drew

On Jan 22, 2016, at 3:02 PM, Douglas Gregor via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@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
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
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
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
Thank you,

-Doug Gregor

Review Manager

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Dave Abrahams) #14

I think the juxtaposition of Array, String, Dictionary, and Set
(mutable, with value semantics) and MutableArray, MutableString,
MutableDictionary, and MutableSet (mutable, with reference semantics) is
one of the most obvious problems with this part of the change.

···

on Sat Jan 30 2016, Drew Crawford <swift-evolution@swift.org> wrote:

I am in favor of this proposal on balance, and I leave the bulk of this to people who interop
with Objective-C more often than I do.

I would like to confine my remarks to one corner where I think we are making a very serious
mistake.

    The removal of the "NS" prefix for the Foundation module (or other specifically
    identified modules) is a mechanical translation for all global symbols defined within
    that module that can be performed in the Clang importer.

As I understand it (and I am no Cocoa historian) the NS prefix was originally introduced
because Objective-C lacks namespacing.

The thinking seems to be that since Swift has proper namespacing, this historicism is no
longer necessary. I find this argument very flimsy.

--
-Dave


(Jacob Bandes-Storch) #15

Proposal link:
https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md

···

On Sat, Jan 23, 2016 at 3:37 AM, Dave Abrahams via swift-evolution < swift-evolution@swift.org> wrote:

That information is all right here, under Platforms:

  https://github.com/apple/swift-3-api-guidelines-review/tree/swift-3

HTH,

--
-Dave

Thank you, I missed that. This is great.

For easier browsing, I've removed comments and @available modifiers from
the generated interfaces:

https://github.com/jtbandes/swift-3-api-guidelines-review/tree/swift-3/Platforms

Jacob


(Dave Abrahams) #16

Is the proposal going to improve support for "c" function import too,
or is it limited to objective-c?

This proposal is only about ObjC methods.

Im asking because there are currently some weaknesses in importing libs
like glibc etc on linux, like the lack of support for functions with
varadic arguments, ie ioctrl etc. Which requires any interfaces to said
functions to have "c" wrappers built for them, before they can be
imported.

Indeed, but it's a separable issue. Let's keep the scope manageable :slight_smile:

···

on Sun Jan 24 2016, Tim Hawkins <swift-evolution@swift.org> wrote:

--
-Dave


(Jacob Bandes-Storch) #17

$ git grep -nHE -e 'func [a-z]*ing\>\(\)' | grep -v 'string()'

  ../../Platforms/OSX/DiscRecording.swift:678: func encoding() -> UInt
  ../../Platforms/OSX/Quartz.swift:1822: func mirroring() -> Bool
  ../../Platforms/OSX/SceneKit.swift:4762: class func spring() ->
SCNPhysicsField
  ../../Platforms/OSX/WebKit.swift:340: func padding() -> String!
  ../../Platforms/iOS/SceneKit.swift:4474: class func spring() ->
SCNPhysicsField
  ../../Platforms/iOS/UIKit.swift:2237: func reversing() -> UIBezierPath
  ../../Platforms/tvOS/SceneKit.swift:4474: class func spring() ->
SCNPhysicsField
  ../../Platforms/tvOS/UIKit.swift:1723: func reversing() -> UIBezierPath
  ../../Platforms/watchOS/UIKit.swift:424: func reversing() ->
UIBezierPath
Except for reversing, these are all fine AFAICT.

Here are some others from the swift-3 branch; I'm not sure where these
currently fall under the guidelines:

CIImage
  func byCompositingOverImage(dest: CIImage) -> CIImage
  func byCroppingTo(rect: CGRect) -> CIImage
  func byClampingToExtent() -> CIImage

(NS)IndexPath
  func removingLastIndex() -> IndexPath

SKTexture
  func generatingNormalMap() -> Self
  func generatingNormalMapWithSmoothness(smoothness: CGFloat, contrast:
CGFloat) -> Self

    class func *darkGray*() -> UIColor
>
> I would rather see this imported as `class var *DarkGray*: UIColor { get
}`.

Why should we capitalize some vars and not others?

I was hoping that colors, and other such types with class methods returning
particular instances, would be treated like enum cases.

enum UIColor {
    case DarkGray
    case Black
    case Clear
    ...
}

enum CAMediaTimingFunction { // more of a job for an overlay, since these
are created with init(name: String)
    case Linear
    case EaseInEaseOut
    ...
}

In the meantime, of course, I saw there was some discussion of having enum
cases begin with lowercase letters as well. I could get used to that. (I'd
just like these to be consistent.)

···

On Tue, Jan 26, 2016 at 1:57 PM, Dave Abrahams via swift-evolution < swift-evolution@swift.org> wrote:


(Matthew Johnson) #18

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.

Interestingly, in at least one case the `WithID` was the original name of the method so we did receive a simple `id` label:

- func parameterWithID(paramID: AudioUnitParameterID, scope: AudioUnitScope, element: AudioUnitElement) -> AUParameter?
+ func parameter(id paramID: AudioUnitParameterID, scope: AudioUnitScope, element: AudioUnitElement) -> AUParameter?

In another case, the method has a naked `With` at the end. Somehow `id` was used in that scenario despite the parameter name being `objectID` and the type being `NSManagedObjectID`, which aligns with my suggested naming:

- func newValuesForObjectWith(objectID: NSManagedObjectID, withContext context: NSManagedObjectContext) throws -> NSIncrementalStoreNode
+ func newValuesForObject(id objectID: NSManagedObjectID, withContext context: NSManagedObjectContext) throws -> NSIncrementalStoreNode

A case related to that used `iDs` for array arguments:

- func managedObjectContextDidRegisterObjectsWithIDs(objectIDs: [NSManagedObjectID])
- func managedObjectContextDidUnregisterObjectsWithIDs(objectIDs: [NSManagedObjectID])
+ func managedObjectContextDidRegisterObjects(iDs objectIDs: [NSManagedObjectID])
+ func managedObjectContextDidUnregisterObjects(iDs objectIDs: [NSManagedObjectID])

I would prefer `ids` here. This seems like a pattern that would be a problem for any all-caps plural acronym or initialism so it might be good to add a heuristic for this as well.

Here’s another interesting change:

- func unionWith(s2: CIFilterShape) -> CIFilterShape
- func unionWith(r: CGRect) -> CIFilterShape
- func intersectWith(s2: CIFilterShape) -> CIFilterShape
- func intersectWith(r: CGRect) -> CIFilterShape
+ func union(with s2: CIFilterShape) -> CIFilterShape
+ func union(rect r: CGRect) -> CIFilterShape
+ func intersect(with s2: CIFilterShape) -> CIFilterShape
+ func intersect(rect r: CGRect) -> CIFilterShape

Why do the CGRect arguments receive a type-derived label but the CIFilterShape arguments just receive `with`? Shouldn’t these follow the same pattern?

-Matthew

···

On Jan 27, 2016, at 1:50 AM, Douglas Gregor via swift-evolution <swift-evolution@swift.org> wrote:

On Jan 25, 2016, at 6:55 AM, Radosław Pietruszewski <radexpl@gmail.com <mailto:radexpl@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

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

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

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Radek Pietruszewski) #19

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.

- 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.

- 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.

- 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.

— Radek

···

On 27 Jan 2016, at 08:50, Douglas Gregor <dgregor@apple.com> wrote:

On Jan 25, 2016, at 6:55 AM, Radosław Pietruszewski <radexpl@gmail.com <mailto:radexpl@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

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

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


(Ben Rimmington) #20

Doug,

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

The related AppKit.NSBezierPath method contains two possible "With" separators:

- (void)appendBezierPathWithArcWithCenter:(NSPoint)center
                                   radius:(CGFloat)radius
                               startAngle:(CGFloat)startAngle
                                 endAngle:(CGFloat)endAngle
                                clockwise:(BOOL)clockwise

Your patch replaces the second "With" separator, but the alternative might be better:

// YOUR PATCH:
func appendWithArc(center center: Point, radius: CGFloat, startAngle: CGFloat, endAngle: CGFloat, clockwise: Bool)

// THE ALTERNATIVE:
func append(arcWithCenter center: Point, radius: CGFloat, startAngle: CGFloat, endAngle: CGFloat, clockwise: Bool)

-- Ben

···

On 27 Jan 2016, at 07:50, Douglas Gregor via swift-evolution <swift-evolution@swift.org> wrote: