2   Quick Fixes Become Quicksand

“You don’t need to really understand that piece of code; it seems to work OK as is. Oh, but it just needs one small tweak. Just add one to the result, and it works. Go ahead and put that in; it’s probably fine.”

We’ve all been there. There’s a bug, and there’s time pressure. The quick fix seems to work—just add one or ignore that last entry in the list, and it works OK for now. But what happens next distinguishes good programmers from crude hackers.

The crude hacker leaves the code as is and quickly moves on to the next problem.

The good programmer will go to the next step and try to understand why that +1 is necessary, and—more important—what else is affected.

Now this might sound like a contrived, even silly, example, except that it really happened—on a large scale. A former client of Andy’s had this very problem. None of the developers or architects understood the underlying data model of their domain, and over the course of several years the code base became littered with thousands of +1 and -1 corrections. Trying to add features or fix bugs in that mess was a hair-pulling nightmare (and indeed, many of the developers had gone bald by then).

But like most catastrophes, it didn’t get like that all at once. Instead, it happened one quick fix at a time. Each quick fix—which ignored the pervasive, underlying problem—added up to a swamp-like morass of quicksand that eventually sucked the life out of the project.

Andy says:

Understand Process, Too

Although we’re talking about understanding code, and especially understanding code well before you make changes to it, the same argument holds for your team’s methodology or development process.

You have to understand the development methodology in use on your team. You have to understand how the methodology in place is supposed to work, why things are the way they are, and how they got that way.

Only with that understanding can you begin to make changes effectively.

Shallow hacks are the problem—those quick changes that you make under pressure without a deep understanding of the true problem and any possible consequences. It’s easy to fall prey to this temptation: the quick fix is a very seductive proposition. With a short enough lens, it looks like it works. But in any longer view, you may as well be walking across a field strewn with land mines. You might make it halfway across—or even more—and everything seems fine. But sooner or later….

As soon as that quick hack goes in, the clarity of the code goes down. Once a number of those pile up, clarity is out the window, and opacity takes over. You’ve probably worked places where they say, “Whatever you do, don’t touch that module of code. The guy who wrote it is no longer here, and no one knows how it works.” There’s no clarity. The code is opaque, and no one can understand it.

You can’t possibly be agile with that kind of baggage. But some agile techniques can help prevent this from happening. We’ll look at these in more depth in later chapters, but here’s a preview.

Isolation is dangerous; don’t let your developers write code in complete isolation (see ​Practice Collective Ownership​). If team members take the time to read the code that their colleagues write, they can ensure that it’s readable and understandable—and isn’t laced with arbitrary “+1s and -1s”. The more frequently you read the code, the better. These ongoing code reviews not only help make the code understandable but they are also one of the most effective ways of spotting bugs (see ​Review Code​).

The other major technique that can help prevent opaque code is unit testing. Unit testing helps you naturally layer the code into manageable pieces, which results in better designed, clearer code. Further into the project, you can go back and read the unit tests—they’re a kind of executable documentation (see ​Put Angels on Your Shoulders​). Unit tests allow you to look at smaller, more comprehensible modules of code and help you get a thorough understanding by running and working with the code.

Don’t fall for the quick hack. Invest the energy to keep code clean and out in the open.

What It Feels Like

It feels like the code is well lit; there are no dark corners in the project. You may not know every detail of every piece of code or every step of every algorithm, but you have a good general working knowledge. No code is cordoned off with police tape or “Keep Out” signs.

Keeping Your Balance

• You need to understand how a piece of code works, but you don’t necessarily have to become an expert at it. Know enough to work with it effectively, but don’t make a career of it.

• If a team member proclaims that a piece of code is too hard for anyone else to understand, then it will be too hard for anyone (including the original author) to maintain. Simplify it.

• Never kludge in a fix without understanding. The +1/-1 syndrome starts innocently enough but rapidly escalates into an opaque mess. Fix the problem, not the symptom.

• Most nontrivial systems are too complex for any one person to understand entirely. You need to have a high-level understanding of most of the parts in order to understand what pieces of the system interact with each other, in addition to a deeper understanding of the particular parts on which you’re working.

• If the system has already become an opaque mess, follow the advice given in ​Damn the Torpedoes, Go Ahead​.