Readable Code - 30 May 2007

Why do so many developer's insist on writing horribly unreadable code? I think it's because they're just plain lazy!

Ok, perhaps that's a little harsh. Maybe it's more correct to say that most developers write unreadable, messy code because they don't see the point in doing any different.

"It's only going to be read by a computer right? And a computer can read code no matter how messy it is so why bother?". Sure, a computer might be able to read it, but people wont!

One of my favorite quotes from this book is - "programs must be written for people to read, and only incidentally for machines to execute". I couldn't agree more.

How many times have you written code that worked first time and never had to be changed again? Probably not very often. The bulk of a piece of code is typically written in one sitting. But it's re-visited over and over again. Every time a defect is found or an improvement is made, some poor sucker has to read the code and figure out what it's supposed to do. And here's the thing... at some point that sucker is going to be you!

Even if you were the original author, chances are you're not going to remember what it does or how it does it. So that leaves you with one option - read it and figure it out.

Here's where things get interesting. If the author bothered to take the time to do things right and write clean, clear, commented code then this can be a simple and pleasant experience. However, if he just cobbled it together because he had to go home and was running late for his train, it can be far from pleasant. What should have taken you a couple of minutes to read and understand can end up wasting an entire afternoon and do terrible things to your blood pressure in the process.

So what do I mean when I say "readable" code? I don't want to get into religious debates on tabs vs spaces or whether to put braces at the end of a line or on the next. That's really not that important. What is important is to write code that is easy for others to read and understand. Here are a few things to consider...

• Don't try to be clever and make things more complicated than they need to be. Keep it simple and to the point. You might think it's cool to use a bitwise left shift instead of just multiplying by 2, but believe me it's not!
• Don't try to optimise your code. First of all you probably don't need to (at least not yet), and second, no offence, but chances are the compiler will do a better job of optimising your code than you can anyway!
• Be consistent. Decide on a coding standard and stick to it, don't just make it up as you go along.
• Be clear about what you're trying to do. If it's not clear, write a comment. But don't waste space with obvious and redundant comments like "iterate through the array".
• Use sensible names. If you choose a poor or misleading name for a class or variable it can make the code incredibly difficult to understand. People will make assumptions based on these names, so take a few minutes to think of names that actually make sense.
• Think before you write. Two minutes of thinking time now could save you hours of pain later.
• Keep it clean. If something isn't used, get rid of it. Don't comment it out, delete it! You can always go back to your source control if you need it.
• Remember that there's no such thing as temporary code. Despite what you might think, the code you're writing right now will probably have a much longer life that you think. So take the time to do it right the first time.
• Finally, as I've said before... don't be lazy!

Basically it all comes down to taking a little pride in your code. You should be able to look back at code you've written and be proud of it. Not only will it make your life easier when you need to re-visit the code, but it will benefit the whole team. If you spend the time doing things right in your code, pretty soon you'll see the external effects of a more solid, reliable and bug-free piece of software.

link