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.

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.