What is good code, and why does it matter?

If you are an experienced developer, you already know the importance of clean code. You know the importance of guarding your codebase against messy code, and you know why it's worth being the annoying reviewer who argues over changes that look inconsequential to everyone else.

But if you're new here—if you've never read code and you're just using AI agents to build it for you—you may not understand the long history behind clean code. And it is a long history. Most developers learn it the hard way.

Every line of code is debt

It's really simple, actually.

It's code you have to maintain and code you have to keep compatible with everything else you've written.¹

Getting disconnected areas of code to talk to each other requires deliberate, intentional, careful architecture. If too many things start talking to each other, it gets messy, and you stop being able to keep track of which part of the code is talking to which. Then you start getting really hairy bugs, some of which just refuse resolution, because the moment you touch one area of the code, ten other areas are affected.

Spaghetti code

That's what's called spaghetti code. It's all tangled up.

Before AirPods, we had wired headphones, and you know how tangled those got.

And sometimes you can't untangle it at all—you have to rewrite it.

This is why developers are always talking about rewriting or refactoring: because the code has become impossible to change.

So when management asks for a new feature that seems like it should take 10 minutes to build—sure, in theory, yes. But in a large existing code base, that 10-minute feature can take weeks, purely because of how hairy the code has gotten.

That's the importance of clean, modular, maintainable code: properly compartmentalized and isolated, so each piece of functionality lives in its own concrete module instead of touching 100 other things.

Why agents are bad at this

Agents are notoriously bad at clean code.

To write clean code, you have to hold the whole code base in your head, and that requires soaking in it for months, if not years. Whenever you join a new company as a developer, it takes many months before you're comfortable enough to write large pieces of code. You might be an experienced software developer with a PhD, but you'll still be outperformed by junior engineers who know that codebase better than you do.

Maintainability is also hard to train agents for. Agents do well with things that have a clear answer: things you can write unit tests for, like mathematics, and things that are verifiable. That's why they've gotten so good at programming.

But there is no verifiable test for whether code is clean, or good, or maintainable. So each individual change an agent makes will look like good code in isolation. But zoom out after days and weeks and months of them adding and adding features, and you'll find they've spaghettified the codebase.

Agents do have an uncanny ability to work through spaghetti in a way humans don't. That might seem like good news. To me it's a little spooky. It feels like something that will explode in your face one day.

Why this matters for you

This is why clean code matters: it stops your code base from freezing up a few months from now.

Even though agents can work with spaghetti, if you're developing new features every single day, fixing bugs, deleting code, refactoring, you will eventually hit a point where the agent can't make a change without breaking several other things. And then you're going to have a really hard time.

This class will cover the principles of what good code is, and how to prompt your agent to deliver it and to review for it. I'll teach you this even if you're not a coder. You'll have the general principles and prompts you need to guard against agents taking advantage of your inexperience to sneak in poor code.

Sources

1. Ward Cunningham, "The WyCash Portfolio Management System," OOPSLA '92 Experience Report, 1992 — the origin of the debt metaphor. c2.com ↩