When to Add Explicit Annotations
Annotate to disambiguate and document intent.
When to Add Explicit Annotations is a free Swift Academy lesson on CoddyKit. This is lesson 2 of 4. Any 3 lessons of this learning path are free to read in full — after that, CoddyKit PRO unlocks every lesson, plus hands-on practice with a built-in code editor and a 24/7 AI tutor. It is part of the Swift Academy learning path, and your progress syncs across the web and the CoddyKit app. The Swift Academy course includes 4 lessons in total.
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)
Learn Swift with an AI tutor — free
Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.
- Courses
- 122
- Lessons
- 409
Frequently Asked Questions
Is the “When to Add Explicit Annotations” lesson free?
Yes — any 3 lessons of the Swift Academy learning path, including “When to Add Explicit Annotations”, are free to read in full here on the web. After that, CoddyKit PRO unlocks every lesson, plus interactive practice with a built-in code editor and a 24/7 AI tutor. The Swift Academy course includes 4 lessons in total.
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, so you can start here or from the beginning and move at your own pace. This is lesson 2 of 4.
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