I know it when I see it.

Good (or bad) code is almost impossible to classify through rigid rules or guidelines. Like Justice Potter Stewart said (in reference to what constituted hard core pornography) “I know it when I see it.”

There are some web sites, such as thedailywtf.com, dedicated to collecting examples of inefficient, confusing, or completely inexplicable code. While they are entertaining to look at, they are so blatant that they are not really a problem in the every-day life of a programmer.

It’s the little things that get you over the long haul. It’s the too-complex method here, the overly elaborate expression there. I went out browsing open-source projects for an example of the kind of thing that makes code more difficult to maintain over the long run and found this in the very first file I saw. I’ve simplified it and removed the product-specific identifiers, to protect the innocent.

do {
    bool res = func();
    if (res) {
       // more processing
    } else
       break;
} while (1);

While being very simple, the choices the programmer made cause it to be difficult to understand at a glance. Here is the equivalent code, using the correct looping structure:

while (func()) {
  //more processing
}

As written, the code is difficult to understand. Why is there an endless loop? Where does the loop terminate? Why? When rewritten using the correct type of loop, its operation is obvious.

Now imagine having to read through thousands of lines of code written like that. It’s difficult enough to understand other people’s logic without the additional stress of deciphering overly-elaborate constructs. Keep it simple.

What’s it like to write code (and who cares anyway)?

I’ve been writing code for basically as long as I can remember. I started programming on a TRS-80 Model I in 1982, and I haven’t stopped since. Sometimes people ask me how I did that, how I “made” myself learn to program. I didn’t, it was just natural to me. I’ve never really treated programming as anything special, any more important to me than say reading, writing, or cooking. But it is important. It’s what I do to earn a living, it’s what I’ve spent most of my adult life doing. And for the foreseeable future it’s what I’ll continue to do.

Not all programmers are the same. When I was at Microsoft, I worked with some of the greatest programmers in the world. And the thing about that is that you already have to be a pretty good programmer yourself to even appreciate the difference between a so-so programmer and a super-star. It’s so technical, so abstract that even a so-so programmer often can’t tell the difference between good code and great code. There are certain qualitites that make code great, and even though I tend to appreciate them without conscious thought, I’ll try to list them.

• succinct — All great code is brief. I’m not saying it’s short, but it’s absolutely no longer than it needs to be. If it needs to be 4 lines long, it is. If it needs to be four pages long, it is (but that happens rarely).
• simple — Great code doesn’t require a lot of effort to understand. The logic behind it is explicit. It doesn’t use tricks and shortcuts to make the programmer look clever. You can go back to great code after five years and understand it just as well as you did the day it was written.
• repetitive — Very well written code tends to consist of repeated patterns, with small variations. This isn’t to say that it has redundancies or blocks of cut-and-paste search-and-replace code. But similar tasks are done using similar means, which increases the likelihood that the code will work as designed. If it works once, it works every time.
• fail-safe — Great code degrades gracefully. When abnormal conditions exist, it fails cleanly. This doesn’t mean that it is cluttered with hundreds of assertions and error tests, but it does mean that variables are always initialized to something safe, conditional statements take possible null values into account, etc.

That’s all I have on great code for now. Maybe I’ll go track down some examples and post them with commentary later.