In his most recent blog posting – In the Eye of the Beholder (ah, reminds me of EoB II), JavaScripter James Padolsey (if you do some JavaScripting / jQuery, follow his blog) argues that the readability of anything is entirely dependent on who’s doing the reading. He also states that readability depends on how proficient the reader is in the given programming language.

I tend to disagree. Readability and understanding are two separate concerns. Readability is about aesthetics. Understanding is about knowledge. Code can be understood without being classified as “readable”.

Here’s my comment on the subject (originally posted as a comment at Padolsey’s blog, but seems to be stuck in WP’s spam filter):

Of course you should assume that the reader is familiar with the language he or she uses. Readability is so much more than that, though.

I should be able to grasp what’s going on in your (or my) code by barely looking at it. I shouldn’t have to read through every block or line in order to “get it”. Like you mentioned in your comment: well named identifiers go a long way in accomplishing this. So does avoiding deep nesting, too many if-else’s, functions that do more than one thing (re-factor your code instead), etc.

Here’s an example from a Norwegian newspaper (http://annonser.dagbladet.no/EAS_tag.1.0.js).

Instead of writing:

function EAS_detect_flash() {

	var maxVersion = 9;
	var isOpera = (navigator.userAgent.indexOf("Opera") != -1) ? true : false;
	var isIE = (navigator.appVersion.indexOf("MSIE") != -1) ? true : false;
	var isWin = (navigator.appVersion.indexOf("Windows") != -1) ? true : false;

	// write vbscript detection if we're not on mac.
	if(isIE && isWin && !isOpera){
		// a lot of document.write's here
	} else if (navigator.plugins) {
		if (navigator.plugins["Shockwave Flash 2.0"] || navigator.plugins["Shockwave Flash"]){
			// some logic from determining support here
		}
	}

	// alert("Version is " + EAS_flash); // yes, we all love to see this in prod. code.

}

They could have written:

function EAS_detect_flash() {

	if( needsVbScriptDetection() ) {
		writeVbScriptDetection();
	} else {
		detectLevelOfShockwaveSupport(); // or something along those lines
	}

}

I assume we all understand the first code snippet, but isn’t the second one easier – and faster – to read? Instead of spending calories parsing variable names, larger blocks, etc., I can happily skip the less interesting parts of the code, spend less time finding bugs, modifying the implementation, etc. And it’s self-documenting. No need for comments here.

This is why the “Clean Code” book should be a mandatory read for any programmer, no matter the language.

An easier way to put it might be that coders should also adhere to Steve Krug‘s usability mantra: Don’t Make Me Think!