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.

38 comments:

ElsaFindlay said...

0204全裸網,777露點聊天室,Hiav潮吹聊天館,utlive脫衣秀聊天室,口交俱樂部,18禁聊天館,影音俱樂部,無碼俱樂部,uthome脫衣秀做愛聊天室,Hiav下載裸照聊天館,777口交自慰俱樂部,0204正妹淫叫俱樂部,uthome脫衣秀做愛,av辣妹大奶,777口交影音,0204正妹淫叫,utlive網,av聊天館,777俱樂部,0204俱樂部,0204全裸網,Hiav潮吹聊天館,777露點聊天室,utlive脫衣秀聊天室,口交俱樂部,18禁聊天館,影音俱樂部,無碼俱樂部,0204正妹淫叫俱樂部,777口交自慰俱樂部,Hiav下載裸照聊天館,uthome脫衣秀做愛聊天室,0204正妹淫叫,777口交影音,av辣妹大奶,uthome脫衣秀做愛,0204俱樂部,777俱樂部,av聊天館,utlive網

有甚麼新歌 said...

18禁貼圖寫真視訊援交露點爆乳潮吹裸體裸照裸女愛愛無碼尋夢視訊聊天a漫a片a圖一夜情一葉情人妻激情情色寫真美女自拍辣妹自拍正妹自拍美女走光辣妹走光正妹走光脫衣秀脫衣走光色情自慰自拍

春天來嚕 said...

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

淑君淑君 said...

免費av成人電影線上免費成人網gogo成人影片a成人短片尼克成人電影成人a免費成人dvd下載成人dvd免費看成人go成人go2成人hbo成人kk俱樂部成人人圖成人大全成人片a片成人片gogo成人片gogosex成人卡通色情片白虎圖庫尼可成人網弘爺論壇打非打非機專用網打炮論壇打飛機專區打砲遊戲打砲網站本土付費av本土成人直播本土自拍小弟弟金瓶梅影片 自拍俱樂部 小高聊天室ol制服美女影片

少菁 said...

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

羅惠玲 said...

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

瑜吟 said...

目標是什麼不重要,目標能產生什麼樣的效果才重要........................................

思穎思穎 said...

恐佈哦~~
相愛?相害?
看了鬼故事之後讓你睡不著覺
洗臉的女孩
紅燒人頭,可好吃了
紅布床簾

和中如勇 said...

謝謝您的分享~感恩唷!!..................................................

GusF_Finkbeiner1209 said...

謝謝您的分享~感恩唷!!..................................................

名青 said...

看看blog放鬆一下,工作累死了.... ..................................................

皓珊 said...

85cc 色情自拍 情色聊天室 色情視訊 情色文學 視訊聊天室 視訊聊天 正妹牆 成人影片 嘟嘟成人網 微風成人 av99影片 85街 撥打電話視訊 情色聊天 UT聊天室 情色視訊 免費視訊 成人視訊 影音視訊聊天室 露點 性高潮 85st 爆乳 0204 一夜 性愛 18禁 尋夢 火辣

韋于倫成 said...

先告訴自己希望成為什麼樣的人,然後一步一步實踐必要的步驟。 ..................................................

紫倫妍勳 said...

人不能像動物一樣活著,而應該追求知識和美德..................................................

ShilaLong嘉雯 said...

人不可以求其備,必捨其所短,取其所長 ............................................................

saa said...

活是一種鍛鍊靈魂的東西......................................................

RoseH_Huls21365 said...

人生是故事的創造與遺忘。..................................................................

秀樺 said...

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

思翰思翰 said...

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

貴寶 said...

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

李豪湖仁陳堅豪 said...

如果成為一支火柴,也要點亮一個短暫的宇宙;如果是一隻烏鴉,也要叫疼閉塞的耳膜。.................................................................

許紀廷 said...

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

JasonBirk佳琪 said...

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

吳婷婷 said...

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

玉婷良DGFHFJ瑋黃吳 said...

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

吳婷婷 said...

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

芳綠 said...

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

琬安琬安 said...

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

魏智偉魏智偉 said...

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

靜詹怡詹詹 said...

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

家唐銘 said...

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

浩子 said...

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

蔡曼鄭美玉屏 said...

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

怡屏 said...

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

洪涛 said...

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

幸平平平平杰 said...

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

孟湖聿軒 said...

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

雯陳俊 said...

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