Code Readability

“Code Nazi.” That’s the phrase that was used to describe me lately. It’s pretty much on target, and I’ll explain why that’s true.

I view source code as part of my trade craft. Perhaps it’s because I work in a service industry and my deliverable is source code, not just binaries. So I spend time thinking about whether it’s well organized, and whether or not someone else can read this enough to take it over? I don’t want to maintain a project for eternity. And I certainly don’t want my customers to feel like I’ve backed them into a corner where only I can maintain the codebase. That’s not good for anybody: me or my customer. Plus, I see it as a reflection of my team and myself, just like any other trade views their works of art. People also have an undeniable tendency hang on to their first impressions. A code base that is clean and readable leaves an entirely different impression than one that is disorganized and poorly formatted. I want the customer to walk away feeling like we paid attention to every detail.

Paying attention to the details is important. It’s all about the details.

Let’s reach back into history and look at how things used to be in books, since reading code shouldn’t really be all that different than reading code. It used to be that sentences were written like so:

thisisareallyhardstatementtoreadbecauseall
thewordsarecrammedtogether.

Interestingly, that looks like half the source code I read:

if(something!=somethingElse){
  MyType mytype=new MyType();
  takeSomeUnreasonableAction(mytype);
  if(mytype.fetchSomething().doSomething()){
    return false;
  }
  return true;
}

Typographers and graphic designers discovered a few things: whitespace and alignment matters. And not just a little bit. It’s the difference between readable and unbearable. It’s the difference between elegant and mediocre. Let’s look at the same example with a little whitespace sprinkled in:

if (something != somethingElse) {
  MyType mytype = new MyType();
  
  takeSomeUnreasonableAction(mytype);
  if (mytype.fetchSomething().doSomething()) {
    return false;
  }
  
  return true;
}

It’s not much white space that has been added into this code block, but look what happens. You can clearly see the conditional–it’s not a function call, which is what it looked like previously. The initialization of the variable is it’s own step, because it’s broken away from the use of it. Then we operate on it, and get some result back out of it–that’s another step. And, if all went well, it’s easy to see that we’d return true out of here.

There’s a flow, and it’s encouraged by the whitespace around it.

This short example doesn’t make much of a difference. Try reading a whole codebase in the previous format, and I guarantee you’ll pull your hair out at the end of the day. Believe it or not, it takes a little extra energy to parse the first block of code, and it quickly adds up over the course of the day. I’m speaking from experience: I’ve read a tremendous amount of code.

So, yeah, I’m a Code Nazi. You read several millions line of code and see where you stand. And just for kicks, head over to the Subversion codebase and see how readable it is. How does your own project standup? Does it say “this software is mediocre?”

Note: for the curious, no, having a great looking codebase doesn’t come first over solving the problem. I am engineer after all: function over form. But having a well-formatted codebase is a very, very close second.

To see some examples of early writing, look at http://en.wikipedia.org/wiki/History_of_western_typography, and in particular, at http://en.wikipedia.org/wiki/File:Trajan_inscription_duotone.jpg.