Style guide, API design guidelines
Use clear names , thoughtful argument labels , sensible defaults , and concise doc comments to design friendly Swift APIs.
Style guide, API design guidelines is a free Swift Academy lesson on CoddyKit — lesson 2 of 3. 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 3 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Principles
Good APIs are readable, predictable, and small.
- Names that describe intent
- Useful argument labels
- Defaults for common cases
- Concise docs and examples
Naming basics
Actions => verbs, data => nouns. Avoid abbreviations that hide meaning.
// Prefer clear, simple names.
// BAD:
func doCalc(_ a: Int, _ b: Int) -> Int { a + b }
// GOOD:
func sum(_ a: Int, _ b: Int) -> Int { a + b }
// BAD (ambiguous):
struct Cfg { let v: Int }
// GOOD (nouns for data types):
struct Configuration { let retries: Int }
print(sum(2, 3)) // 5Argument labels
Labels help call sites read naturally: remove(at:), insert(_:at:).
// Choose labels that explain a parameter's role.
// BAD:
func remove(_ index: Int) { print("remove", index) }
// BETTER:
func remove(at index: Int) { print("remove at", index) }
// Mixed labels:
func insert(_ item: String, at index: Int) {
print("insert", item, "at", index)
}
remove(at: 2)
insert("a", at: 1)Good defaults
Use default parameters to keep common calls short while still offering flexibility.
// Provide defaults to cover the 80% case.
func greet(_ name: String, times: Int = 1, shout: Bool = false) {
let msg = shout ? "HELLO, \\(name)!" : "Hello, \\(name)!"
for _ in 0..<times { print(msg) }
}
greet("Ana") // default: once, not shouting
greet("Ben", times: 2)
greet("Cara", shout: true)Effects & mutability
Make effects visible: use mutating methods for state changes and expose read-only views with private(set) when appropriate.
// Prefer pure functions when possible; name mutating effects explicitly.
struct Counter {
private(set) var value = 0
mutating func increment(by amount: Int = 1) { value += amount }
}
var c = Counter()
c.increment()
c.increment(by: 3)
print("value =", c.value) // 4Documenting APIs
Doc comments tips:
- Start with a single-sentence summary.
- State what it does, not how.
- Show a tiny example call.
- Note preconditions or performance gotchas only if important.
Label usage rationale
Quick check: When should you add an external label?
Recap
Recap: Prefer clear names, add labels that read well, offer defaults for common calls, make effects explicit, and keep docs short with an example.
Frequently asked questions
Is the “Style guide, API design guidelines” lesson free?
Yes — the full text of “Style guide, API design guidelines” is free to read here on the web, and the Swift Academy course includes 3 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 “Style guide, API design guidelines”?
Use clear names , thoughtful argument labels , sensible defaults , and concise doc comments to design friendly Swift APIs. 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 3, so you can start here or from the beginning and move at your own pace.
How long does the “Style guide, API design guidelines” 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
- SwiftFormat / SwiftLint basics
- Style guide, API design guidelines
- Documenting code (DocC intro)