When you've worked with a concept long enough, there's a gap that can quietly open up between "I know how this works" and "I can explain exactly why this works, including the edge cases that trip people up." Writing a tutorial closes that gap fast — readers will hit exactly those edge cases, and a good article needs to anticipate them.
Before publishing the article on Swift function parameters — external vs internal names, the _ underscore, default values — I ran a quick exercise: a batch of small function snippets, some valid and some subtly broken, each one checked line by line. The goal wasn't to test whether I understood parameters — it was to stress-test the explanations themselves, and make sure they'd hold up against exactly the kind of "looks right but isn't" code a learner might write. 🍥
Why Bother With This, If the Concept Is Already Familiar
Knowing a rule and being able to anticipate every way someone might misapply it are different things. Parameter labels are a great example — the rules themselves are short, but the ways they interact (single name vs two names, _ vs labeled, what happens at the call site vs inside the function) create a surprising number of combinations. Going through deliberately-broken snippets is a fast way to make sure an explanation covers the combinations that actually confuse people, not just the ones that are easy to describe.
A Few Snippets Worth Including in the Article
The "two names that look like one" trap
func makeBurger(withCheese: Bool) {
if cheese {
print("Here's a cheeseburger")
} else {
print("Here's a regular burger")
}
}
This is a great teaching example precisely because it looks fine at a glance — cheese reads as obviously related to withCheese. But Swift doesn't do "obviously related." withCheese is the parameter name (both external and internal, since only one name was given), and cheese was never declared. This is exactly the kind of mistake a learner makes when they understand the concept of parameters but haven't internalized that Swift matches names exactly, not by similarity.
The "duplicate label" trap
func formatLength(length length: Int) {
print("That measures \(length)cm.")
}
formatLength(95)
This one's useful because it stacks two separate issues: the length length: syntax is invalid when both names are identical, and the call site formatLength(95) is missing a required label even if the declaration were fixed. A good explanation needs to address both — it's easy to fix one and assume the snippet is now correct, when a second issue remains.
The one most likely to surprise readers: skipping return
func square(_ number: Int) -> Int {
number * number
}
No return keyword, and it's completely valid — Swift allows a function body that's a single expression to implicitly return that value. For an article, this is worth calling out explicitly with its own example, separate from the surrounding explanation, because seeing it in isolation — without context cluing the reader in that something special is happening — is closer to how a reader will encounter it "in the wild" in someone else's code.
What This Exercise Is Really For
The value here isn't "I learned something new about Swift." It's that going through concrete pass/fail examples, one at a time, surfaces the gap between a correct mental model and an explanation that anticipates where readers will get confused. The cheese/withCheese example is the clearest case — the underlying rule (Swift matches names exactly) is simple to state, but an explanation that doesn't show why a plausible-looking mismatch fails won't actually prevent the mistake.
Where AI Was Useful Here
For this kind of exercise, having a tool that could generate a steady stream of varied snippets — some valid, some subtly broken in different ways — and walk through each one line by line on request made it easy to cover a wider range of "near-miss" cases quickly than working through a fixed set of pre-written examples would have. It functioned less like a teacher and more like a sparring partner for testing explanations against fresh cases.
Worth Doing Before Publishing
If you write technical tutorials, this is a cheap pre-publish check: take the rule you're about to explain, and try to generate a handful of snippets that are almost correct but fail for a specific, nameable reason. If you can't immediately produce several, your explanation might be covering the easy 80% and leaving readers to discover the other 20% the hard way — in the comments. 🌸
Top comments (4)
I liked the idea of pressure testing the explanation rather than the concept itself. Many bugs and misunderstandings happen in those small edge cases that seem obvious at first glance. The cheese/withCheese example was a great one :)
Really glad that framing landed! The cheese/withCheese example is such a good one precisely because it looks fine at first glance — your brain fills in the connection between the two names without realizing Swift won't. Those are exactly the cases worth hunting for before publishing an explanation.
the sparring partner framing is more useful than it sounds. the same dynamic shows up when writing agent tool descriptions or system prompts — you think you've specified exactly what the tool does, then an LLM finds a plausible input that's almost right and breaks the boundary you didn't know was implicit. running "generate near miss inputs that should fail" against a tool spec catches the same gap you're describing: the 20% your mental model glosses over.
the implicit return example transfers most directly. "works but nobody expects it" is the failure mode that creates confusion in both tutorial readers and agents.
do you use this process for other languages, or does Swift's parameter rule surface area make it especially worth the effort?
The parallel to agent tool descriptions is really interesting — "generate near miss inputs that should fail" as a way to find the implicit boundaries you didn't know were there is exactly the same exercise, just applied to specs instead of syntax. The gap between what you think you specified and what an LLM finds plausible is a great way to describe the same problem from a different angle.
To your question — honestly Swift's parameter rule surface area is what made this feel worth formalizing. The combinations of external/internal names, _, default values, and call-site labels create a lot of "looks right but isn't" possibilities in a small space. Other languages have their own versions of this, but Swift's explicitness about call-site labeling makes the near-miss cases especially instructive. I'd probably reach for this process with any language that has a lot of small interacting syntax rules — it just surfaced naturally here first.