It's Coming: the Great Swift API Transformation

Dave Abrahams Dave Abrahams

Cocoa, the Swift standard library, maybe even your own types and methods—it’s all about to change, and you can help determine how.

Ever since before Swift was released, there’s been a style gap between Cocoa interfaces and APIs in the Swift standard library; lots of things just look different, often needlessly so. This is no mere aesthetic concern; non-uniformity and lack of predictability make everything harder, from coding to debugging to maintenance. Fortunately Swift developers created tons of great code in spite of that gap, and along the way, there evolved a sense of what “Swifty” code looks and feels like.

Informed by that experience, when looking at our APIs, it’s easy to see there’s room for improvement, both in the way the compiler imports Objective-C APIs—where the results just don’t seem quite comfortable in Swift—and in the Swift standard library, which lacks a level of regularity and coherence that Cocoa users have come to expect. So we at Apple decided to do something about it.

In order to converge Cocoa and the standard library, we needed a target to shoot for: a unified, written approach to API design that everyone could follow. We started by going back and questioning all our old assumptions. Existing guidelines were fantastic, but much of the material was geared to Objective-C, didn’t cover Swift-specific features such as default arguments, and more importantly, were not informed by the emergent sense of “Swiftiness” that we felt was so important to capture.

As we developed these guidelines we applied them to the standard library, all of Cocoa, and a couple of sample projects. We evaluated the results, refined, and repeated. Before Swift went open source, we’d have done this all behind closed doors, and presented you with the results in the next release, but a new era has dawned on Swift: it’s time to show the world what we’ve been up to. Here’s a tiny example of how code looks before transformation:

class UIBezierPath : NSObject, NSCopying, NSCoding { ... }
...
path.addLineToPoint(CGPoint(x: 100, y: 0))
path.fillWithBlendMode(kCGBlendModeMultiply, alpha: 0.7)

and after:

class UIBezierPath : Object, Copying, Coding { ... }
...
path.addLineTo(CGPoint(x: 100, y: 0))
path.fillWith(kCGBlendModeMultiply, alpha: 0.7)

We’ve put three parts of this proposed transformation up for public review in Swift’s evolution group: changes to how Cocoa is imported, changes to the surface of the standard library, and the API guidelines that tie this all together. Suggestions for improvement have already started coming in from participants, and we’re able to see how they affect APIs.

For example, one suggestion we’ve explored changes this call:

path.addArcWithCenter(
  origin, radius: 20.0,
  startAngle: 0.0, endAngle: CGFloat(M_PI) * 2.0, clockwise: true)

into this:

path.addArc(
  center: origin, radius: 20.0,
  startAngle: 0.0, endAngle: CGFloat(M_PI) * 2.0, clockwise: true)

Will we make this change? The jury is out, but this is the time to make your voice heard. The review period has been extended through Friday, February 5th. If you’d like to help shape the future of your language and frameworks, join the discussion. The proposals and associated review threads are here: