When you read an article on programming, most of the code samples are deliberately contrived. But the best samples have a common element: function and variable names very clearly describe their purpose.

That’s not a coincidence. The code is written so that someone reading it can figure out what it does.

But I’m guessing your code never seems to read so clearly. Your variables have shortened names and you type fewer comments because using fewer keystrokes means having a smaller chance of getting carpal tunnel. Your variables are declared where you think you might use them, even if you never do (I was shocked at how often I actually left them in the code, and I only realized it once I started looking at the warnings in Visual Studio .NET). And you never explain your logic because, well, someone can just ask you if they really want to know, right?

But when authors write articles, they are presumably writing them to be read. If nobody reads them, then their efforts have been wasted. That’s not quite the case with your code. Even if nobody reads it, it still does what it’s supposed to. And I suppose that’s fine if you’re writing code by yourself. Except it’s not really all that fine because you probably won’t be able to understand that code in a couple years anyway. My point is that if the code is written to be understood, then the code will be understood.

Good writers get paid well because they are good at communicating with words. Maybe developers should get paid well for communicating with code. A former professor of mine notes that “over half of the money and effort spent on the software product is spent during maintenance and evolution.” If you have code that’s been written to be read – as well as function – then maintenance costs will drop.

I feel like every code snippet written should be forced to be presented to the public. That way, the incentive to make code unreadable would just disappear. Maybe I’m being a little too hopeful, but it can’t all that bad an idea. I mean, if you have enough pride to rubber duck, then you shouldn’t be embarrassed to explain your code to a real, live human.

I tried this recently while writing some code for an open-source microcontroller project. I was working with a mechanical engineering friend who has a basic understanding of programming. We weren’t working on anything too complex, so I figured that he should at least be able to read the code, even if he wasn’t going to be writing it from scratch.

The code worked, but it wasn’t pretty, and he asked me to walk him through it. When I did, I found myself uttering words I didn’t really want to hear – things like “it could probably be made a little clearer” and “this is kind of a hack, but…”. He was right to suggest that this was why existing code was so hard to deal with.

Writing good code goes beyond merely getting it to work. It also involves considering how the code will be used in the future. Yes, it’ll be used by a computer, but the code also needs to be used by people:

You must consider the needs and capabilities of other people. For instance, if you are a programmer who refuses to be bothered to write readable code, then testing and maintenance of your code will be a great burden, if not an impossibility.

You can’t afford to be selfish when it comes to programming as part of a team. You need to show empathy, which basically means putting yourself in someone else’s shoes. There are plenty of examples of how not to care about the people who need to read your code.

So keep that in mind before your check-ins.

(Update: I decided to take my own advice and re-write some of my code to improve readability.)