Join Scott Gardner for an in-depth discussion in this video Understand the Swift API design guidelines, part of Swift 3 First Look.
- [Voiceover] The Swift API Design Guidelines should apply as much to code you write for an open source library that you create or contribute to, as to your own AP project code. Swift has it's own personality that is uniquely different from Objective-C. A major initiative is underway, dubbed the grand renaming, to modify the API originally written in and for Objective-C that is imported into Swift, to make it more, Swifty, and this even includes dropping the NS prefix from foundation API. The primary goals of the API Design Guidelines are to reduce redundancy, and increase usability and readability at the call site.
These goals can be achieved by adhering to just three basic principles. Strive for clarity for the user of your API. Overly clever code can confuse the best of us, even ourselves a couple months later, when we need to go back and read code we've previously written. Swift does pride itself on its succinctness, but that should not imply terseness of style. Type and property names, enumeration cases, function and parameter names, and even local values declared within the function body should be descriptive. Function names and parameters should read grammatically in line like a sentence.
This self documenting nature of well-written functions for example, doesn't mean that we shouldn't also document them to explain the intent in each parameters role, as well as the value returned, or for types of properties, what their purpose is, especially for code that will be shared in an open source library or even across a team. There's nothing more reassuring when you're reading unfamiliar code and you option click on the function name and get a delightful quick help comment to explain things. It truly inspires confidence, and it can also help you design better API.
Expanding upon these fundamentals, some good best practices to follow include: omitting redundant and unnecessary words, as a simple example, why write UIColor.greenColor? Do we really need to repeat color here? This tells the whole story. Or how about some of that string API, which is rife with redundancy that can be removed to improve clarity. When naming a function, a verb is usually a good choice for the base name, while descriptive or prepositional terms can be used for parameter names, and nouns are typically good choices for return values.
So for example this function reads, add fresh ingredients to cookingVessel and it returns a meal and then at the call site, add fresh vegetable to wok. Reads just like a sentence. This was referred to as the ed/ing rule in the API guidelines session at WWDC. The basic gist is, use "ed" or "ing" for non-mutating methods and use the root verb for a mutating methods. For example, sort is a mutating method, but sorted and trimmingCharacters are both non-mutating.
Now that I've gone over the goals, basic principles, and best practices of the Swift API Design Guidelines, let's take a look at some of the new types created in foundation relevant to these API Design Guidelines.
Get your first look at Swift 3 in this course with Scott Gardner. Scott demonstrates changes made to the Swift Standard Library and Cocoa and Cocoa Touch APIs and reviews the Swift API Design Guidelines, identifying key principles and best practices that will help you optimize your Swift code. Also, check out the migration case studies in chapter 3, which show how to upgrade existing projects to Swift 3.