01 · Complexity is the real problem

When you finish this lesson you should be able to:

• Point at complexity as the thing you are managing, not “more features”
• Separate three symptoms: change that fans out, brains that overflow, and surprises
• Describe a messy product in two minutes without listing every file

Core idea

Software gets hard when it takes more and more effort to do the same kind of work. The useful word for that is complexity. Speed, clever algorithms, and framework trivia are secondary. If you cannot say why a change is expensive, you will spend the hour decorating the wrong problem.

Complexity is not the same as “lots of code.” A large, boring module with one job can be simple to use. A small tangle where every field knows about every other field is complex.

Watch for three symptoms:

1. Change amplification — one product ask forces edits in many places.
2. Cognitive load — a reader must hold too many facts to make a safe edit.
3. Unknown unknowns — the dangerous parts are not obvious, so you only learn them by breaking production.

Those symptoms have two common causes: dependencies (this only works if that is in a particular shape) and obscurity (the important fact is not where you look). Dependencies are not automatically bad. A checkout flow should depend on a payment result. They become expensive when they are implicit, circular, or scattered.

Complexity is incremental. Nobody ships a ball of mud on purpose. Each “just this once” leak of knowledge, each extra flag, each special case named after a customer, adds a little. The senior move is to notice the slope, not to wait for a rewrite.

Example

Imagine in-app messages: welcome, receipt, “your card failed,” “try this experiment.” Product wants a new “quiet hours” rule. In a tangled design, quiet hours is copied into the push sender, the email sender, the in-app inbox, the experiment assigner, and a cron that retries. One rule, five edits, easy to miss one. That is change amplification.

A simpler story: one delivery policy answers “may we send this, to this person, right now?” Push, email, and inbox call that policy. Quiet hours lives in one place. The senders still exist, but they do not each reinvent the rule.

When you talk this through, do not inventory every service. Name the symptom (“quiet hours fans out”), name the cause (“the rule leaked into every channel”), and name the bet (“hide the rule behind one question”).

Drill (12 minutes)

Talk out loud. No editor required.

1. Pick a product you know: flags, notifications, or first-run onboarding.
2. Name one upcoming change (a new rule, a new channel, a new audience).
3. For that change, say which symptom you expect: fan-out, overloaded reader, or hidden landmine.
4. Point at one dependency that should exist, and one that is accidental.
5. Stop. Do not design the whole system.

If you wander into a ten-box architecture, you failed the drill. The skill here is naming the pain.

Further reading

• A Philosophy of Software Design — Chapter 2, The Nature of Complexity