Pressure-Testing My Own Explanations — A Swift Writing Exercise

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. 🌸