In Clean Code, Martin doesn’t just name the best practices we should all be following. He explains the reasoning behind each one and gives names to the concepts. Just as the idea of software design patterns revolutionized the way we think and talk about software architecture, Martin’s exploration of day-to-day coding habits gives us a smarter way to think and talk about that.

Case in point: Clean Code kicks off with the practice of giving your objects meaningful names. One aspect of this is that good names do not require anyone who might read your code in the future to have to perform any “mental mappings.” Here’s an example of this that I came across just the other day.

var ld = new LoginData();

Look carefully, that’s a lower-case L. At first glance, it looks like a capital I, as in “ID,” as in “identifier.” I don’t know how long I spent confused about how a class constructor could be returning an identifier when reading through this code for first time. Maybe ten or fifteen seconds? Time in which I was completely distracted from understanding the rest of the code, having pushed that problem onto the stack, as it were, in order to first solve this mini-problem.

Even without the I vs. L confusion, using an abbreviated variable name meant that whenever I came across it, I had to keep reminding myself that it stood for an instance of LoginData. That may not seem like a big deal, but we humans only have so much stack space before we run out of short-term memory. When a program is full of one- and two-letter variable names that must be continually translated mentally, it leaves no room for thinking about the actual problem that the program is trying to solve.

All of this could have been avoided if the name was spelled out to begin with, so I changed it (using the automated rename refactoring tool in my IDE):

var loginData = new LoginData();

“One difference between a smart programmer and a professional programmer is that the professional programmer understands that clarity is king. Professionals use their powers for good and write code that others can understand.” ~ Robert (Uncle Bob) Martin

Martin could have just said, “don’t use abbreviations in variables names, because you’ll make the reader translate it in his head every time he reads it,” and that would have been terrific advice alone. But what he really gives you is a deep understanding of the key principles involved, so that you won’t need to memorize a bunch of arbitrary coding standards in order to write cleaner code. Instead, you’ll be armed with a few simple, understandable principles to guide you, with clean code being the natural outcome.

Clean Code is a must-read for everyone in the software profession — from college freshmen on up to CTOs — especially anyone who finds himself out of work in this economy (or worried about the possibility). Learning to write clean code, and thus to write more valuable code, is probably the single most effective thing you can do for yourself. Programmers are expensive resources. The work we produce is costly. It’s up to us to treat it with the respect it deserves, to try and make it as valuable as possible, and to maintain that value as long as possible.

It’s taking best practices to the extreme…

• Long iterations become short iterations with early experience
• Long, irregular meetings become frequent stand up meetings
• Back-end testing becomes unit testing
• Specification artifacts become stories and a full-time customer (proxy)
• Enforced deadlines become developer-derived estimates
• Code reviews become pair programming

The XP Values

• Communication
• Feedback
• Simplicity
• Courage

The Tenets of Extreme Programming & Refactoring

• Establish a guiding vision, or “metaphor,” and then design as you go, with no big, up-front design.
• Do the simplest thing that works, at first, and then refactor as needed.
• No “Spec Gen” (speculative generality). Rely on refactoring to add features only as they actually become required.
• No speculative performance tuning. Rely on refactoring to introduce performance tuning later.
• Code in small iterations and fast release cycles.
• Put unit and functional testing at the core of the project goal posts, not as an optional add-on. In fact, write the tests before you write the code to be tested. You cannot rely on refactoring without a complete baseline of unit tests.
• Do not refactor and add functionality at the same time. Alternate between them.
• Coding standards should have buy-in by all team members and call for the least amount of work possible.
• Work directly with an on-site customer and/or user and make them a part of the programming team.
• The customer determines the priorities, not the developers.
• Developers provide the estimates, not the customer.
• “Spikes” are written when preliminary research is required to provide a confident estimate.
• The entire development team has collective ownership of the entire project. It is not portioned-out code to individual experts.
• Program in pairs to assure quality and stay on track.
• Use stand-up meetings to stay on track.
• Stick to a 40-hour workweek, sleep well and lead a balanced, healthy lifestyle.

Getting Started

1. Kent Beck’s “Extreme Programming Explained” (second edition) is the seminal work in the field. It’s an easy read and it paints a good overall picture.
2. Martin Fowler’s “Refactoring: Improving the Design of Existing Code” is a must-read. The first 100 pages describes refactoring (and a bit about test-driven development). The remaining pages are a catalog of refactorings — essentially a cookbook of step-by-step recipes.
3. Robert Martin’s “Agile Software Development” has also been recommended as a good starting point, though it’s not primarily about XP.

I’m helping out with a study group for “Head First Design Patterns,” which just finished chapter 6. On the whole, it’s a pretty good introduction to software design patterns — way more accessible than the seminal work by the Gang of Four; however, the examples sometimes make my head hurt. I can’t imagine what they’re doing to the heads of the beginners in the group. Coming up with decent examples is the hardest thing to do in expository writing, and I certainly give the authors an E for effort in creativity, but I wish they had been a little less concerned with making their examples “hip” and a little more concerned with making them appropriate.

To wit, the whole pizza store analogy in chapter 4 (to illustrate factory method and abstract factory) is flawed. For one thing, that’s just not the way you’d model a pizza business in any actual software that I can imagine. For another, the differences between a New York pizza factory and a Chicago pizza factory are too subtle/trivial to make for an effective illustration of why you would need to subclass anything (much less use a factory to manage the subclasses). A much better example, as everyone in my group agreed, would have been an application that needs to offer up a consistent set of functionality to users who are accessing it in wildly different ways: one’s in a web browser on a desktop, another is running a cell phone app, another is using a touch-tone phone, and yet another is using a voice-activated headset. All the client code knows is that, for example, it needs to ask a multiple-choice question and obtain the answer. It’s up to an abstract factory to provide the client with a set of classes that can do that, in the context of the selected user-interface, in whatever way is necessary.

To a lesser degree, the Starbucks coffee example at the beginning of the book suffers from the same too-hip-to-be-effective syndrome, although I do think that the remote-control example for the Command pattern in chapter six is dead on.

For any novice who is reading this book without the benefit of a study group, I highly suggest that you find at least one other programmer who is experienced in design patterns to explain why/if/how the examples are lacking.

In the field of cognitive psychology there’s this so-called “Magic Number 7.” Basically, the idea is that humans can only keep 7 disjointed “things”, plus or minus two, in short-term memory at once. To see what I mean, study the following list of words for a minute. Then, turn away and write down as many as you can from memory:

Apricot, ladder, storm, headphones, spark-plug, sneaker, anchor, coin, library, twenty-seven, lyrics, nail, telescope, onion.

How’d you do? I could only recall nine of them (even though I was the one who made up the darn list just now), and in fact, I had to work hard to recall the eighth and ninth. By the way, IQ has nothing to do with this number. Whether you’re closer to Mensa or Densa, your short-term recall factor will still be 7 +/- 2. (See Wikipedia and George Miller’s 1956 paper that first noted the phenomenon is at www.musanim.com/miller1956/.)

As the Wikipedia article points out, Ed Yourdon first commented on how this relates to computer science back in 1979. He described what we would today refer to as the long-method smell (see www.soberit.hut.fi/mmantyla/BadCodeSmellsTaxonomy.htm), citing the magic number 7 as why it’s bad to tax the short-term memory of someone trying to understand a piece of code.

So, how often does your web framework require you to keep track of more than seven things at once? Take, for example, the simple task of creating a data-entry page. How many different files need to be created or modified to accomplish this? One for the HTML template, one for the page logic, multiple files for each model object (interface, impl, and ORM mapping), the DAO (interface and impl), the config file with the URL construction rules, the config file with the user security rules, the config file that lists all of the pages on the site, the interface file with constants for all those page names? — That’s eleven and counting. Sound familiar? This amount of complexity often leads to things falling through the cracks, and is usually reflected in a high number of bug reports.

From what I have seen, Ruby on Rails has made this particular task as simple as it can be, and that accounts for a great deal of RoR’s appeal, I’m sure. Even .Net has this down cold. In the case of RoR, it’s an innate feature of the framework. In the case of .Net, it’s simplified by the tools. I’m still waiting for a Java-based framework/environment that “gets it” in this regard.

Quoting myself, “Then, as I do the work for real, it gives me an acid test to know if I’m on the right track. In other words, does the software now work as advertised? A side benefit of this end-first exercise is that it often reveals latent issues and questions for which I have no answers. It also helps me to enumerate any assumptions that I’ve been making, which perhaps ought to be validated.”

This is a very much akin to Test-First Development (a.k.a. Test-Driven Development, or TDD for short), of which I am a huge proponent. I’d almost say that what I described above is a poor man’s version of TDD, except that there is no cost to doing TDD. Unit testing tools are free for the asking.