Agile Zone is brought to you in partnership with:

I have been writing code since 1980. In 1999, I learned Java and after discovering IntelliJ the love was complete. XML and XSLT was a revelation in 2000, too bad the standards committees have done so much damage since. Contributed to the Flying Saucer open source XML and CSS rendered and published an open source XSLT generator, weffo. Currently employed by Google. Torbjörn is a DZone MVB and is not an employee of DZone and has posted 9 posts at DZone. You can read more from them at their website. View Full User Profile

Clarity of code is clarity of thought

  • submit to reddit
I remember at my first job when we introduced the concept of code reviews. I don't think anybody really looked at anybody else's code before pressing the "approve" button, I know I didn't. Reading code is boring and it can be hard and it felt like a waste of time. I had my own code to write and why shouldn't the author of the code have written it right in the first place?

When I moved to another job, they talked about how, in theory, code reviews was the number one most effective way to increase code quality. But they had given up on it, because they felt it came down to a discussion of where to put the dots and commas (or, rather, semi-colons and parentheses).

Quite aside from the issue of code reviews, I had come to realize that I spent much more time reading my code than I spent writing it. Every debugging session is spent reading code over and over. Every time you have to add a feature or change some functionality you have to read the code, and re-read it to avoid breaking stuff. Don't tell me tests will do it for you. Now don't get me wrong, tests are great and I strongly advocate test-first coding, it's a great way to achieve focus and clarity of thought. But when a test fails, you're thrown into debugging mode, which means reading code.

So I concluded it was worth spending a little extra time typing longer variable names, and taking the time to find descriptive names. It was worth spending a little more time breaking down those long methods and simplifying those complex structures. Whenever I was reading code that made me stop and think, I would usually refactor it to be clearer (although the term refactoring hadn't been invented yet). I would also change existing code to make a new feature fit in better, in a more readable and more logical way.

In "The Pragmatic Programmer" the distinction is made between "programming by coincidence" and "programming by intention". We all have to do it occasionally, a little trial-and-error programming, because we're not quite sure how things work. That's "programming by coincidence". Before you check your code in, you want to make sure you understand what each statement does and that all unnecessary statements are removed. Then you've transformed the code from coincidental to intentional.

But that's not enough. Your very functional and intentional code is going to lose you valuable time unless you also transform it to readable code, which clearly displays your intent.

A much-touted wisdom is that you should document and comment your code. Fair enough, that works, but it has many weaknesses. Your energy is far better spent making the code explain itself. Comments often lie, but the code is always pure truth, so prove it in code. Only comment on "why" you are doing something, and that only if you cannot make it evident in the code.

I like the following sound-bite from "Refactoring": "Any fool can write code that a machine can understand, it takes a good programmer to write code that a human can understand."

Test-first "anything" is efficient and focused because it sets up the criteria for success and the means to measure it up front. So what's the best way to test if your code is readable? Get another person to read it, i.e. a code review.

I'm very grateful to those who review my code carefully and pick on every detail, it makes the code better and it helps assert that my thinking was clear. That gratitude gives me the energy to return the favour by reviewing their code equally mercilessly.

You will sometimes, but rarely, find bugs by just reading code (only because everybody has a brain-fart now and then). But the real value of the reviews is in the "dot and comma" discussions and especially in picking good names. In addition to making sure that the code is easy to read, it will sometimes bring a real little nasty bug to the surface.

An example: An index into an array of values is stored into a variable called "value". When the reviewer makes you change the name to "valueIndex" instead, some parts of your code may start to look weird (the bug was exposed).

Clarity of code really is clarity of thought.
Published at DZone with permission of Torbjörn Gannholm, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)


Jack Hung replied on Mon, 2009/08/31 - 2:37am

100% agreed with your opinion on the importance of code readability.

But Java is too verbose :( and no matter how hard you tried, your code just couldn't quite say what you meant. That gives rise to design patterns, attempting to relief some of the pains of Java deficiency.

Try take a look at a Groovy/GORM ( or Rails/ActiveRecord ( program code and you'll see the different the language makes.

Even Javascript can be more expressive than Java :(


Bruno Vernay replied on Mon, 2009/08/31 - 5:42am

Funny, that there is also a recent a post in Artima's forum about 

... a recent paper by Gilles Dubochet, Computer Code as a Medium for Human Communication: Are Programming Languages Improving?, measured eye movements of people reading Scala code written in three different styles: a Java-like, looping style and two versions of a more idiomatic Scala style that used for expressions and higher-order functions instead of loops: one with meaningful variable names and one without....

The paper has to be taken with a grain of salt, as explained in the comments.  But it is interesting to see scientific usability technics used to measure language readability.


Torbjörn Gannholm replied on Mon, 2009/08/31 - 3:06pm in response to: Bruno Vernay

Cool, thanks for the reference!

Torbjörn Gannholm replied on Mon, 2009/08/31 - 3:11pm in response to: Jack Hung

I have full respect for your opinion and you may well be right. However, I'm not sure I would consider another language more readable if I'm not familiar with it and the idioms commonly used. Also, often the language is chosen a priori for you. A good programmer will then write code that is readable in the style of that language and not try to introduce foreign concepts which will look, uh, foreign...

Benjamin Nelson replied on Thu, 2009/11/26 - 5:11am

It doesn't sound like writing code is that much different than writing article, except of course the phenomenal expertise that coders have. Writers spend more time reading than writing.

Slava Imeshev replied on Thu, 2009/09/03 - 1:23am

It looks like what you are talking here is Literate Programming: "Literate programming is defined as the combination of documentation and source together in a fashion suited for reading by human beings" [1]

A must read on the topic is Donald Knuth's "Literate Programming" 

Hope this helps.


Slava Imeshev





Torbjörn Gannholm replied on Thu, 2009/10/01 - 11:27am in response to: Slava Imeshev

Literate programming seemed like a really good idea in the 90's but it still suffers from the concept of documentation being something separate from the code itself.

john green green replied on Fri, 2009/11/27 - 12:01pm

A much-touted wisdom is that you should document and comment your code. Fair enough, that works, but it has many weaknesses. Your energy is far better spent making the code explain itself. Comments often lie, but the code is always pure truth, so prove it in code. Only comment on "why" you are doing something, and that only if you cannot make it evident in the code.
nike china shoes

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.