The Swift API Design Guidelines could be one of the most important things I’ve found towards writing cleaner Swift code. Have you seen them yet? I hadn’t actually looked at them until I watched the WWDC video, “Swift API Design Guidelines.”. When chatting with a coworker about which WWDC video to watch during some downtime, I’ll admit that this video didn’t really catch my eye. As someone who doesn’t really write much “framework” type code for other people to consume besides those I directly work with, I didn’t immediately relate to the description for the video:
Swift 3 introduces new API Design Guidelines specifically crafted to the unique character of Swift for clear, concise code. This talk will explore the philosophy behind the Swift API Design Guidelines and their application throughout the Swift Standard Library and the Cocoa and Cocoa Touch APIs. See how this API transformation will affect your Swift code and learn how to ensure a smooth transition to Swift 3. Learn how Swift 3 imports Objective-C APIs and how to expose rich Swift interfaces for existing Objective-C libraries.
Well having watched the video, and then read through the actual design guidelines on Swift.org, I’m bought in, and recommend you take a look as well.
The Swift API Design Guidelines is like an instruction manual for how to craft the “words” in your code: how you name variables, parameters, method names. It tells you how to interweave the words in your code with the surrounding documentation. By becoming familiar with the Swift API Design Guidelines, you’ll both write code that is consistent with the community, and the APIs that are being created within the frameworks right out of Apple and the Swift team. It’s a win/win proposition.
Here are the highlights of the Swift API Design Guidelines for me:
The “ed/ing” rule
The presenter in the WWDC video summed this rule up as the “ed/ing” rule (that makes it easy for me to remember). In the Swift.org documentation, it’s referred to as Name functions and methods according to their side-effects in the Strive for Fluent Usage section. The guideline suggests that often, “A mutating method will often have a nonmutating variant with similar semantics, but that returns a new value rather than updating an instance in-place.” According to the ed/ing rule, append ed or ing to the nonmutating version. For example:
Mutating
x.sort()
x.append(y)
Nonmutating
z = x.sorted()
z = x.appending(y)
Omit Needless Words
Boy, if there’s one bad habit that is leftover from Objective-C is really wordy method names, particularly be repeating words. For example, just look at the NSMutableArray Objective-C class documentation and take a peak at how many times the word “object” appears. Methods like this are all over the Objective-C Foundation API:
- (void)addObject:(ObjectType)anObject;
- (void)removeObject:(ObjectType)anObject;
Just look at how many times the word “object” appears in the class documentation for NSMutableArray. As a result, this verbosity made its way into the code that I wrote as well.
Well this is a no no in Swift. The Swift creators are striving for a balance of conciseness AND clarity.
Although Swift code can be compact, it is a non-goal to enable the smallest possible code with the fewest characters. Brevity in Swift code, where it occurs, is a side-effect of the strong type system…
The last part of this section is relevant. It’s the strong type system that allows for the NSMutableArray API to be redesigned as:
func add(_ anObject: AnyObject)
func remove(_ anObject: AnyObject)
Notice how the word “Object” was removed from the method name itself? That’s exactly what is meant as a “needless word” in the guideline “Omit Needless Words.” This is because consumers of this API can rely on the strong type system of Swift to only pass objects to the method that are of the defined type of the parameter. This is just one example where Swift API Design Guideliness lead us to more concise code through omitting needless words. Now that you’re aware of it, you’ll start to see this all over and should even apply it to your own API design.
Also, be sure to check out the sections in the Swift API Design Guidelines for Name variables, parameters, and associated types according to their roles and Compensate for weak type information. Detailed examples are not included here, but those guidelines provide good companion structure how to achieve clarity while also ommitting needless words. Remember, don’t strive for brevity over clarity. Just like the WWDC presenter mentioned, you don’t want to have to constantly be switching to the API docs because the API is so terse.
Grammatical English Phrases
Method and function names should read like grammatical English phrases. I really like this one, and I feel like this is one good habit I’ve carried from my dark days as a Java programmer. This is also covered in the String for Fluent Usage section of the Swift API Design Guidelines. A good sanity check for your method and parameter names is to read the line of code aloud and ask yourself, “Is this grammatically correct English? Is this how I would conversationally say it?” If yes, then you probably are on to a good API design. If not, you should probably reconsider it. Examples right from Swift.org of good API design that grammatically makes sense:
x.insert(y, at: z) // “x, insert y at z”
x.subViews(havingColor: y) // “x's subviews having color y”
x.capitalizingNouns() // “x, capitalizing nouns”
Bad design that doesn’t read aloud well:
x.insert(y, position: z)
x.subViews(color: y)
x.nounCapitalize()
Other Random Cool Stuff
Documentation
In the handful of programming languages that I’ve professionally written, I’ve never come across such a succinct yet well defined set of guidelines for writing code documentation. It’s right at the top of the Fundamentals section of the Swift API Design Guidelines. There are short and sweet points to consider when writing documentation for your Swift code, and also how to make your comments compatible with how Xcode might represent them in generated documentation.
Conventions
The Conventions section is really cool too. There are a lot of one-off suggestions to help clarify everything from when to document Big-Oh efficiency, to how to capitalize your variable and method names.
Wrap Up
I can’t urge you strongly enough to check out the Swift API Design Guidelines on Swift.org. I can tell you that in my opinion it is one actionable thing that you can do to improve your Swift code, today. It’s simple, clear, and instructional manner makes it really easy to understand. Your code will be more consistent with itself, and code written elsewhere in the community. Who wouldn’t want that?
Happy cleaning.
One thought on “Swift API Design Guidelines: Highlights”