Complexity

Podcast 2 — In conversation

Speaker A: We had a code review yesterday that got quite heated. One reviewer kept saying the component was too complex, but another said it was just difficult. It felt like they were talking about different things.

Speaker B: They probably were. That distinction actually matters in software. Difficulty is a measure of effort — how hard it is to understand or write. Complexity is a structural property — how many interacting parts there are.

Speaker A: So something can be difficult without being complex?

Speaker B: Absolutely. A single line of bit manipulation code can be very difficult to understand but structurally simple — just one operation. Whereas a well-documented orchestration service might have high complexity — dozens of moving parts — but be straightforward to reason about if the design is clear.

Speaker A: And the reverse — complex but not difficult?

Speaker B: Yes — a well-abstracted system hides its internal complexity behind clean interfaces. The complexity is there, but it doesn't become difficulty because it's been managed properly.

Speaker A: So managing complexity is actually a specific skill in engineering?

Speaker B: A core one. There are formal metrics — cyclomatic complexity measures how many paths exist through a function. Tools like SonarQube will flag functions with high complexity scores and suggest refactoring. Reducing complexity isn't about making things simpler for its own sake — it's about keeping the code testable and maintainable.

Speaker A: And at a higher level — system architecture?

Speaker B: At that level you talk about accidental complexity versus essential complexity — a distinction from Fred Brooks. Essential complexity is the irreducible complexity in the problem itself. Accidental complexity is the extra complexity we introduce through our tooling, our architecture choices, our conventions. Good engineering eliminates accidental complexity while acknowledging that essential complexity cannot be removed.

Speaker A: So complexity has a kind of budget — there's a floor you can't go below?

Speaker B: Exactly. The domain has a minimum complexity level. Everything you do beyond that minimum is overhead you've chosen to carry. The goal is to know which complexity is essential and which is self-inflicted.

Speaker A: That's a genuinely useful mental model. What's the most common misuse of the word?

Speaker B: Using complexity as a compliment. People say this system has a lot of complexity as if that signals sophistication. It doesn't — unnecessary complexity is a liability. Complexity only earns its keep when it solves a real problem that couldn't be solved more simply.

Podcast 3 — Prompt engineering

Instructor: Complexity as a noun in AI prompts does something different from the adjective complex. It invites the AI to reason about measurable properties, trade-offs, and systemic qualities — not just the nature of a thing, but how much of a quality it possesses. Let's work through examples.

Student: So it triggers more analytical responses?

Instructor: Yes — it's a signal that you want the AI to evaluate, measure, or reason about degrees. First example: code quality.

Instructor: PROMPT: Analyse the time complexity and space complexity of this binary search tree implementation. Identify which operations are O of log n in balanced cases and which degrade to O of n in unbalanced cases. Suggest how an AVL tree or red-black tree could be used to bound the worst-case complexity.

Instructor: Naming both time complexity and space complexity separately tells the AI to produce a two-dimensional analysis. The word complexity here is doing precise technical work — the AI will use Big-O notation and reason about worst and average cases.

Student: And for refactoring?

Instructor: PROMPT: Refactor this Express.js route handler to reduce its cyclomatic complexity. The current function has too many nested conditionals. Extract validation logic, error handling, and business logic into separate functions. The goal is a cyclomatic complexity score below 5 per function.

Instructor: Cyclomatic complexity score below 5 is a concrete target — the AI will produce smaller functions with fewer branches because you've given it a measurable goal, not just a vague instruction to make the code cleaner.

Student: What about when designing a new system?

Instructor: PROMPT: Design a microservices architecture for a retail platform that deliberately minimises accidental complexity. Document which services are required by the essential complexity of the domain, and which architectural choices could be simplified without losing necessary functionality.

Instructor: Accidental versus essential complexity is a precise framing from software theory — the AI will use this lens to produce a reasoned architecture, not just a service diagram. The vocabulary elevates the quality of the output.

Student: Something about managing complexity over time?

Instructor: PROMPT: Create a complexity budget policy for a frontend codebase. Define thresholds for maximum file length, maximum function complexity, and maximum component props. Describe what triggers a complexity review and what the remediation process should be.

Instructor: Complexity budget is a real engineering governance concept. The AI will produce a policy document with thresholds, not just general advice. Using the precise vocabulary means the AI produces a production-ready artefact.

Student: And for explaining complexity to non-technical stakeholders?

Instructor: PROMPT: Write a one-page technical brief for a non-technical product manager explaining why the complexity of our payment integration has increased after adding three new payment providers. Explain what essential complexity is unavoidable and what technical debt is contributing additional accidental complexity.

Instructor: Using essential complexity and accidental complexity in a stakeholder brief frames the conversation productively. It separates what management cannot control from what the engineering team can address. Precision vocabulary enables clearer organisational decision-making.

Student: Complexity really is doing measurement work in these prompts.

Instructor: Exactly. It transforms vague concerns like this is hard to maintain into a technical property that can be measured, bounded, and managed. When you use complexity precisely, you're not describing a feeling — you're invoking a discipline.