API Design Guidelines
- Proposal: SE-0023
- Authors: Dave Abrahams, Doug Gregor, Dmitri Gribenko, Ted Kremenek, Chris Lattner, Alex Migicovsky, Max Moiseev, Ali Ozer, Tony Parker
- Review Manager: Doug Gregor
- Status: Implemented (Swift 3)
- Decision Notes: Rationale
This review is part of a group of three related reviews, running concurrently:
- SE-0023 API Design Guidelines (Review)
- SE-0006 Apply API Guidelines to the Standard Library (Review)
- SE-0005 Better Translation of Objective-C APIs Into Swift (Review)
These reviews are running concurrently because they interact strongly (e.g., an API change in the standard library will correspond to a particular guideline, or an importer rule implements a particular guideline, etc.). Because of these interactions, and to keep discussion manageable, we ask that you:
- Please get a basic understanding of all three documents before posting review commentary
- Please post your review of each individual document in response to its review announcement. It's okay (and encouraged) to make cross-references between the documents in your review where it helps you make a point.
The design of commonly-used libraries has a large impact on the overall feel of a programming language. Great libraries feel like an extension of the language itself, and consistency across libraries elevates the overall development experience. To aid in the construction of great Swift libraries, one of the major goals for Swift 3 is to define a set of API design guidelines and to apply those design guidelines consistently.
The proposed API Design Guidelines are available at https://swift.org/documentation/api-design-guidelines/.
The sources for these guidelines are available at https://github.com/apple/swift-internals. Pull requests for trivial copyediting changes are most welcome. More substantive changes should be handled as part of the review process.
Impact on existing code
The existence of API Design Guidelines has no specific impact on existing code. However, two companion proposals that apply these guidelines to the Standard Library and via the Clang importer will have a massive impact on existing code, changing a significant number of APIs.