Friday, August 28, 2009

Clarity of code is clarity of thought

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.

23 comments:

Anonymous said...

may the blessing be with you.........................................

Anonymous said...

I love readding, and thanks for your artical. ........................................

Anonymous said...

Judge not of men and things at first sight.......................................................

秀樺 said...

感謝你的分享 要繼續發表好文章喔

Anonymous said...

幸福不是一切,人還有責任。....................................................................

Anonymous said...

當一個人內心能容納兩樣相互衝突的東西,這個人便開始變得有價值了。............................................................

Anonymous said...

我們老得太快,卻聰明得太遲。..................................................

Anonymous said...

越來越多人看你的部落格 要繼續加油喔 ..................................................................

Anonymous said...

All roads lead to Rome. 堅持自己所選!..................................................................

Anonymous said...

天道酬勤,blog也是!相信你的用心會讓你更受歡迎的............................................................

Anonymous said...

出遊不拘名勝,有景就是好的............................................................

Anonymous said...

德不孤,必有鄰。文不獨,必有應!............................................................

Anonymous said...

良言一句三冬暖,惡語傷人六月寒。......................................................................

Anonymous said...

人生像一杯茶,若一飲而盡,會提早見到杯底..................................................

Anonymous said...

新的一天 祝你有所成長~~ ............................................................

家唐銘 said...

想別人怎樣對你,你便怎樣對待別人。......................................................

Anonymous said...

我在戀愛著?--------是的,因為我在等待著..................................................................

蔡曼鄭美玉屏 said...

看到大家都留言-我也忍不住說聲---加油..................................................

Anonymous said...

每日都有新日光,每日都有新希望。.................................................

Anonymous said...

I love readding, and thanks for your artical.............................................................

幸平平平平杰 said...

祝福大家開開心心。............................................................

孟湖聿軒 said...

你怎麼能經過一片海,而忘記它的藍?......................................................................

雯陳俊 said...

與人相處不妨多用眼睛說話,多用嘴巴思考............................................................