Coding for Readability

It is a widely accepted fact in the development community that the average developer will spend more time reading - or rather understanding - code than writing it. The most simplistic analysis of your day-to-day work will bear out this hypothesis, and if you aren’t a fan of anecdotal evidence there are plenty of people who have got you covered (ok, that last one *is *anecdotal, but it’s written by Jeff Atwood so I’m counting it).

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live

But despite the readily available evidence to this effect, I’m not convinced that many of us really take it on board. If the balance between reading and writing is so vast, surely the only sensible thing to do is to write your code primarily with readability in mind? I’m not limiting this statement to things such as naming conventions and comments; I’m talking about how a piece of code scans.

When you are skimming through an instruction manual trying to find the elusive piece of information to solve your problem, you just want to jump straight to the answer, not read the whole damn thing. So you skim the section headings until you find one that look’s about right and THEN you read the detail. Can you imagine the pain of trying to find an answer if every time you found something that looked like the answer you had to read the 10, 20, 30 lines before it to check?

Unfortunately, that is exactly how a lot of code seems to turn out. For comparison, take a look at the block of code below. It is well commented, has fantastic variable names and is certainly not hard to understand…

//go through all the people and check that the names are capitalized
foreach (var person in _people)
{
//keep a record of whether or not we need to save this person
var needToSave = false;

//check the first name
if (!person.FirstName[0].IsUpper())
{
	person.FirstName = string.Format("{0}{1}", 
				person.FirstName[0].ToUpper(),
				person.FirstName.substr(1));
	needToSave = true;
}

//check the last name
if (!person.LastName[0].IsUpper())
{
	person.LastName = string.Format("{0}{1}",
				person.LastName[0].ToUpper(),
				person.LastName.substr(1));
	needToSave = true;
}

//update the repository if we made changes
if (needToSave)
	_repository.CommitChanges();
}

…once you read it. And that’s pretty much the problem - I don’t need to read it. I’m not interested in capitalising names; I’ve been trying to track down a tricky bug all morning and I’m running out of coffee.

Now if that same block of code looked like this:

this.CapitalizeNames();

…then I don’t need to do anything except skim over it: “CapitalizeNa…already moved on”.

This approach has other benefits like promoting discoverability and making the code self-documenting, but most importantly it means that you don’t have to read the whole manual to find the part that you want.

So if ever you are writing a piece of code that takes more than a casual glance to understand, please please just put it in a method with a nice simple name - the guy who ends up reading it will thank you.