Code readability: The 5 minute explanation test.

As the great man, Albert Einstein, once reportedly said:

"If you can't explain it simply, you don't understand it well enough."

I was reading an article by Alberto Gutierrez on makinggoodsoftware.com and within the article he touches upon a technique that we *sometimes-but-not-often-enough* take.

He explains the 5 minute explanation test, as:

1. Grab a fellow programmer, who can spare some time, to review your code
2. Walk him through your code, just a high level introduction.
3. Ask him if he understood your code.

After following the 3 steps you can evaluate how readable your code is based on how much effort & time it took you to explain it. Alberto says:

"as a rule of thumb if it takes more than 5 minutes for the other programmer to have a high level idea of the design, assume that the code is not readable."

A good example of the 5 minute test often occurs when the code is broken and you seek help from colleagues (rather than presenting your most polished code). This can be a true test of your general coding style.

Conducting the approach does throw up some instant (and perhaps obvious) questions.

1. How much commenting is overkill?

2. Is the code complex for complex sake, or include tricks?

3. How much abbreviation should be allowed?

4. Does it follow a set standard

Of course the answer to these questions is debatable, and you will find many blog posts and articles arguing the detail.

For us, it comes down to common sense and common ground. If people disagree and it leads to debate amongst the tech team, then that is a good thing, and provided a consensus is met - then we have progressed. We may not have the golden bullet approach (does one exist?), but it should allow for people to pick up our code and get going without too much head scratching.

I don't want to preach in this post, as lord knows - I have written poor code in my past (you'd be a liar if you (are a programmer) said you hadn't). But I found a piece of freelancer code from a long, long time ago that allows me to tackle most of the above points.

/**

* Really sorry for this, I need to refactor it but I haven't got time now

**/

function reOptInCallBack($param) {

$urls = array(); //Create an empty array

for ($i = 1; $i <= 5; $i++) {  //Loop 5 times

$urls[] = $this->getCBUrls($param); //Get CB Urls to return

}

return $urls;

}

 

There are so many things wrong with this code that I am not going to be able to cover them all. In an attempt to relate them to the above questions I'd say the following:

The first comment explaining the function is simply ridiculous. I think I'd almost rather have no comment - as it simply infuriates, rather than puts the developer at ease, as an apology. If you don't have time, don't commit it. Or at the very least make some effort to explain what you intend to fix and change, so that I have something useful as a starting place.

The next comments are equally useless. Thanks for telling me what array() and "for" does! If I don't know the language constructs etc then I won't likely be trying to do something with it. If comments are necessary then tell me why the number 5 and why you have to loop, not how the code is doing it, but why.

The other comment (Get CB Urls to return) - this is just repeating the function call. In fact it gives me 0 extra information. I also detest of abbreviation like this. I can guess (although why should I have to?) that CB stands for CallBack as it is mentioned as the function name, but why not stay consistent and call it getCallBackUrls?

I have no idea what "re" does on reOptInCallBack, so maybe the chance to explain it would have been useful instead of the rubbish apology.

I could go on all day about how bad this code is. It has failed almost every question raised, the developer who wrote it certainly would have failed the 5 minute explanation test if they had run it by me (or any other self respecting coder).

The item that peeves me the most is the comments, and I think Ryan Campbell has a nice quote about commenting code:

"Commenting your code is like cleaning your bathroom—you never want to do it, but it really does create a more pleasant experience for you and your guests"

This bathroom in-particular was smelly, in need of refurbishment and broken!

I truly believe that if we all wrote code that considered future developers our solutions would be vastly more elegant and friendly.