8
8
If Objective-C is required, additionally refer to the [ Google Objective-C Style
9
9
Guide] [ 3 ] .
10
10
11
- ## Guidance {:#guidance}
11
+ ## Guidance
12
12
13
- ### New APIs should be Swift-only {:#new-apis}
13
+ ### New APIs should be Swift-only
14
14
15
15
Swift is the preferred language for Apple development, so new Firebase APIs
16
16
should be fully optimized for Swift. When designing new APIs, consider whether
@@ -24,13 +24,13 @@ corresponding generated Swift interface should be manually refined to be more
24
24
idiomatic. Apple provides a [ guide] [ 4 ] for improving such Objective-C API
25
25
declarations for Swift.
26
26
27
- ### Include Swift code samples {:#include-swift}
27
+ ### Include Swift code samples
28
28
29
29
It is important for new APIs to be as easy to use in Swift as possible. When
30
30
creating a proposal, prioritize Swift code samples to demonstrate the new API's
31
31
usage.
32
32
33
- ### Async API should be written in async/await form {:#async-api}
33
+ ### Async API should be written in async/await form
34
34
35
35
Swift has built-in [ support] [ 5 ] for writing asynchronous code. If a
36
36
callback-based API is required, it should be carefully considered and justified.
@@ -45,7 +45,7 @@ public func fetchData() async throws -> Data { ... }
45
45
public func fetchData (completion : (Data, any Error ) -> Void ) { ... }
46
46
```
47
47
48
- ### New APIs should be Sendable {:#new-apis}
48
+ ### New APIs should be Sendable
49
49
50
50
A [ Sendable] [ 7 ] type is one that is thread-safe and can be shared safely across
51
51
multiple concurrency contexts. The requirements for conforming to the Sendable
@@ -54,7 +54,7 @@ introduces strict concurrency checking and enforces Sendable types in
54
54
asynchronous code. If applicable, new APIs should be Sendable and designed to be
55
55
used in an async context (e.g. ` Task ` ).
56
56
57
- ### API Availability {:#api-availability}
57
+ ### API Availability
58
58
59
59
By design, an API may not be available on a given Apple platform. Swift supports
60
60
platform-specific compilation and runtime checks.
@@ -81,7 +81,7 @@ product's CocoaPods podspec, and declare it on the API's signature via the
81
81
func myNewAPI () { ... }
82
82
```
83
83
84
- ### Constants {:#constants}
84
+ ### Constants
85
85
86
86
In Objective-C, constants were usually defined at the global level. In Swift,
87
87
constants can instead be grouped under a case-less enum. The benefit of a
@@ -95,7 +95,7 @@ public enum NetworkConstants {
95
95
}
96
96
```
97
97
98
- ### Minimizing optionals {:#minimizing-optionals}
98
+ ### Minimizing optionals
99
99
100
100
Unlike Objective-C, Swift handles nullability in a type safe way using
101
101
[ optionals] [ 10 ] . While useful, avoid overusing them as they can complicate
@@ -141,13 +141,13 @@ public struct CustomValue {
141
141
func setValues (_ values : [String : CustomValue]) async throws { ... }
142
142
```
143
143
144
- ### Documentation {:#documentation}
144
+ ### Documentation
145
145
146
146
New APIs should have corresponding documentation using [ Swift-flavored
147
147
Markdown] [ 13 ] . Xcode can generate a documentation block's structure when the
148
148
cursor is in the method signature and ⌥ ⌘ / is pressed.
149
149
150
- ### Naming Conventions {:#naming-conventions}
150
+ ### Naming Conventions
151
151
152
152
[ Swift's official API design guidelines] [ 1 ] provide an overview to creating
153
153
idiomatic Swift API.
@@ -167,14 +167,14 @@ Consider the precedent set by the existing API that is adjacent to the new API
167
167
being added. New APIs should be consistent with the existing Firebase API
168
168
surface, and diverge only when justified.
169
169
170
- ### Errors {:#errors}
170
+ ### Errors
171
171
172
172
If the new API can fail, mark the API as ` throws ` and create (or add onto) an
173
173
existing public [ error] [ 15 ] for the API to throw. Swift provides an ` Error `
174
174
protocol that can be used to create descriptive errors that can be easily
175
175
handled by clients.
176
176
177
- ### Don't define typedefs {:#don't-define}
177
+ ### Don't define typedefs
178
178
179
179
_ This guideline only applies when changing public Objective-C API_ .
180
180
0 commit comments