When to Add Explicit Annotations
Annotate to disambiguate and document intent.
When to Add Explicit Annotations is a free Swift Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Swift Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Why Annotate
Even though inference is powerful, explicit type annotations improve clarity, resolve ambiguity, and document intent.
let temperature: Double = 36
print(temperature)
print(type(of: temperature))Forcing a Double
Without an annotation, let x = 5 is an Int. Annotate to make it a Double when you need fractional math later.
let count: Double = 5
let average = count / 2
print(average)Empty Collections
An empty literal has no elements to infer from, so you must state the type explicitly.
var scores: [Int] = []
scores.append(10)
print(scores)Empty Dictionary
The same rule applies to empty dictionaries: annotate both key and value types.
var ages: [String: Int] = [:]
ages["Ada"] = 36
print(ages)Disambiguating Overloads
When several initializers could match, an annotation tells the compiler which one you mean.
let small: Int8 = 100
let big: Int64 = 100
print(type(of: small), type(of: big))Documenting Stored Values
In stored properties, explicit types are required and act as documentation for readers.
struct Account {
var balance: Double = 0
var owner: String = "Unknown"
}
let a = Account()
print(a.balance, a.owner)Annotating for Readability
For long or non-obvious expressions, an annotation helps readers know the result type at a glance.
let ratio: Double = 22 / 7
print(ratio)Optional Types
You often annotate optionals explicitly because nil alone has no inferable type.
var nickname: String? = nil
nickname = "Ace"
print(nickname ?? "none")Closures Returning Nothing
When a stored closure could be ambiguous, annotate its full type.
let action: () -> Void = {
print("ran")
}
action()Numeric Literal Conversions
Annotations let a single literal flow into different numeric types without manual conversion calls.
let cpu: UInt8 = 255
let wide: UInt32 = 255
print(cpu, wide)Balance Inference and Annotation
Rule of thumb: let inference handle obvious cases, and annotate when the type is ambiguous, when it improves clarity, or when required (empty collections, properties, parameters).
let obvious = "clear" // inference is fine
let precise: Double = 9 // annotation needed
print(obvious, precise)Quick Check
When is an annotation required?
Recap
Add explicit annotations to force a specific numeric type, to declare empty collections and optionals, to disambiguate overloads, and to document properties and APIs. Otherwise let inference keep code clean.
var list: [String] = []
let rate: Double = 5
print(list, rate)Frequently asked questions
Is the “When to Add Explicit Annotations” lesson free?
Yes — the full text of “When to Add Explicit Annotations” is free to read here on the web, and the Swift Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Swift Academy course, upgrade to CoddyKit PRO.
What will I learn in “When to Add Explicit Annotations”?
Annotate to disambiguate and document intent. You practise Swift Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Swift Academy?
No prior experience is required. Swift Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “When to Add Explicit Annotations” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Swift Academy lesson?
Yes. Every Swift Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- How Type Inference Works
- When to Add Explicit Annotations
- Inference with Literals
- Inference in Closures