Readability Counts

In 2006, psychologist Daniel Oppenheimer won an Ig Nobel Prize for his research paper "Consequences of Erudite Vernacular Utilized Irrespective of Necessity." He researched vocabulary used in everything from resumes to academic essays, and found that the easier the texts were to read, the higher the readers judged the author's intelligence. This included anything that made the text hard to read, including "big" words and even the font type used.

It helps me to remember that coding is explaining. And not just to the computer, but to yourself and to others.

The nice thing is that you don't have to write perfect code (which is impossible anyway). It just needs to be understandable to you and others. If you can write code simply so that everyone can understand it, then you will come across as a much better programmer than you otherwise would.

The cleaner your code becomes the more side-benefits you will also notice such as having less fatigue when working with it and having less bugs!

If you run the python prompt and enter:

    >>> import this

It will output "The Zen of Python" message by Tim Peters:

     Beautiful is better than ugly.
     Explicit is better than implicit.
     Simple is better than complex.
     Complex is better than complicated.
     Flat is better than nested.
     Sparse is better than dense.
     Readability counts.
     Special cases aren't special enough to break the rules.
     Although practicality beats purity.
     Errors should never pass silently.
     Unless explicitly silenced.
     In the face of ambiguity, refuse the temptation to guess.
     There should be one-- and preferably only one --obvious way to do it.
     Although that way may not be obvious at first unless you're Dutch.
     Now is better than never.
     Although never is often better than *right* now.
     If the implementation is hard to explain, it's a bad idea.
     If the implementation is easy to explain, it may be a good idea.
     Namespaces are one honking great idea -- let's do more of those!

It's pretty sad that we still need to remind each other that readability counts (which was pointed out in the May of 2010 "Zen of Python" episode of the "From Podcast Import Python" podcast).

Sometimes the problem is that the code author has yet to read a book on how to write readable code.  But they are definitely out there.

A book written in the 1970's by Brian Kernighan, a little before I was even born, entitled "The Elements of Programming Style" spoke of how the best documentation for a computer program is a clean structure. It also helps if the code is well formatted--with good mnemonic identifiers and labels. And a smattering of enlightening comments.

And again in 1999, Brian Kernighan coauthored another great book with Rob Pike called "The Practice of Programming" and outlined that the main principles are: "Simplicity," which keeps programs short and manageable; "Clarity," which makes sure they are easy to understand, for people as well as machines; "generality," which means they work well in a broad range of situations and adapt well as new situations arise; and "automation," which lets the machine do the work for us.

A few other seminal works, such as "The Pragmatic Programmer: From journeyman to master", Code Complete: A practical handbook of software construction", and of course Bob Martin's "Clean Code: A handbook of agile software craftsmanship", all go into great detail on how to write readable and maintainable code.

From my experience, a general rule is if you're looking at a piece of code and all you can say about it is "Boy, this sure is convoluted", then it's probably not clean code. If you can understand the code right away, it may or may not be well-written; perhaps you're just used to reading poorly written code. However, if it seems like the code is so nice that it actually gives you a good feeling -- or at least doesn't give you a headache from squinting -- then it's clearly readable code.

A few of the main guidelines for writing readable code are:

     - Your functions / classes should be doing only one thing each.
     - Your variable names should not require comments
     - Use adequate whitespace and consistent indentation.

There are many more things you can do, and that differ between a normal code base and when designing APIs, and I refer you to the aforementioned books.

References:
59 Seconds: Change your life in under a minute
Science Daily
From Python Import Podcast