What a system asks of you

The interesting question in a codebase is rarely does this work. It is what does this make easy, and what does it quietly make expensive. A function that saves four lines today and forces every future caller to remember an ordering constraint has not saved anything.

Three things I keep coming back to:

• The shape of the data decides the shape of the code. Change the model and half the awkward call sites stop being awkward.
• Every abstraction is a bet about which direction the requirements will move. Some bets are cheap to lose; take those.
• Coupling you can see is better than coupling you cannot. An explicit dependency is a design decision; an implicit one is a trap for whoever comes next.

A small example

The version that reads best is usually the one where the types make the invalid state impossible to write down:

enum LoadState<Value> {
    case idle
    case loading
    case loaded(Value)
    case failed(Error)
}

Two booleans and an optional describe the same four states, plus twelve that should never exist. You will spend the life of the feature defending against those twelve.

The purpose of a system is what it does, not what it was intended to do.

Where it stops working

The analogy has a limit. Chess ends. Software does not, and the position you are optimising for is one you will still be sitting in three years from now with a different team. That changes what counts as a good move: legibility starts to beat cleverness by a wide margin.

More on this in Migrating a core tab, which is the same argument applied to something narrower.

Start at the leaves

The instinct is to rebuild the container first — the tab, the navigation, the coordinator — and fill it in. That is the version that stalls, because nothing ships until all of it works, and the branch ages badly against a codebase twenty other people are changing.

Going the other way works better: replace the smallest leaf screen, ship it, then the next one. Each step is a normal feature-sized change that a reviewer can hold in their head.

• Every step is independently shippable, so the work survives a reprioritisation.
• Bugs are attributable. When something regresses you know which screen did it.
• The container is migrated last, by which point it barely does anything.

The seam is the hard part

Hosting a SwiftUI view inside a UIKit stack is trivial. Keeping two navigation models honest about who owns the back button is not:

final class LegacyHost: UIHostingController<DetailView> {
    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        // The UIKit parent still owns the chrome until the whole tab moves.
        navigationController?.setNavigationBarHidden(false, animated: animated)
    }
}

That line is the entire migration in miniature. Two systems, one of which thinks it is in charge, and a boundary you have to keep explicit until the older one is gone.

What actually slows you down

Not the UI. The UI is the part with a clear finish line. The slow parts are the analytics events that fired from viewDidAppear and now need somewhere honest to live, the A/B assignment read at a point in the lifecycle SwiftUI does not have, and the deep links that pointed at a view controller by name.

The old code is not badly written. It is written against assumptions that stopped being true, and it never got told.

Knowing when to stop

The goal was never a SwiftUI app. It was a tab that a new engineer can change without reading five years of history first. Some of the old code clears that bar already, and rewriting it buys nothing but risk. Leave it.

Suspension points are the API

Every await is a place where the world can change underneath you. State you read before it may not hold after it.

func refresh() async {
    let stale = cache.snapshot()
    let fresh = try? await service.fetch()   // anything can happen here
    apply(fresh ?? stale)                     // is `stale` still current?
}

Actors fix the data race and not the logic race. Serialised access means two tasks will not corrupt the same field; it does not mean the second one is still doing something that makes sense.

Things worth being deliberate about

• @MainActor on the type, not scattered across its methods.
• Structured tasks over detached ones — cancellation should follow the tree.
• Sendable warnings are the compiler telling you where the boundary is. Do not silence them; move the boundary.

More once this is written properly.

The shared lesson

A move that only works if nothing else changes is not a move, it is a liability with a delay on it.

• In chess you ask what squares this gives up.
• In a codebase you ask what this makes harder to change.

They are the same question. Neither has a good answer available in the moment you most want one.

Where the analogy pays

Tempo. Shipping is not only about the feature; it is about who has to move next and how constrained they are when they do. A change that leaves the next person with three good options is worth more than a slightly better change that leaves them with one.

Full version to follow.