On reading code

Last week I started using github, forked a project, and read some of miyagawa's beautiful code. Later on the weekend, I imitated a particular style I found from his code to improve my own code.

And then I realized: during the course of many years as a programmer, I really really seldom read other people's code, especially real-world code. Sure, I do whenever I have to patch something. But other than that, practically never.

Other than code, I do read an awful lot: books, magazines, mailing lists, forums, blogs, web pages. I have never doubted the benefits of reading for improving knowledge and understanding, so why haven't I read more code? A couple of reasons I can think of:

1. We programmers are not paid to read code. We are paid to write programs, to churn out lines upon lines of code. Heck, we're not even paid to write good code, we're paid to get the job done.

2. Reading code is hard. It can really drain your brain. Imagine a recipe book where the flow of instructions is not linear (jump to line X, jump to page Y and then return here), where a misplaced character can destroy the whole recipe, and where everything is so interdependent and interlinked that you need to read everything twice first before you can begin to understand it.

3. Reading code is boring. Can you really curl up with a good program the way you can with an exciting novel?

4. Reading code is not necessary. A good reusable piece of code need not be read anyway, all you need is its API documentation. Programmers are hired regardless of their ability to read real-world code, there are no interview tests in reading code other than a few or at most a dozen lines of it. Heck, programmers are even hired despite their inability to write any code at all.

After experiencing that one session of code reading can do some wonders, I'll make it a program to read more (good) other people's code.


Ah, but the trick is finding good code. ;)

I am curious...what "style" did you copy and why?

I pretty much disagree with your reasons.

1. Every place I've ever worked as a programmer, I wasn't paid to write code. I was paid to solve problems: fix bugs, add features, stuff like that. If I could do it by modifying existing code, or deleting code, or downloading some library (assuming licensing was okay), that work was considered just as valid as writing new code.

I seem to remember some studies that showed that the majority of software development is the "maintenance" phase after the initial ship, even for waterfall projects (and much more so for better-run projects), and the majority of "maintenance" consists of understanding the existing code base to figure out how to make a change, so that about 50% of the time spent on a software project consisted of reading code.

2. Yes, although well-structured code is easier to read, and it does get easier over time.

3. Most code is boring, but for the same reason that most of the manuscripts in a book editor's slush pile are boring, plus the additional drawback that a lot of code wasn't even written with readability as its theoretical primary objective, while the slush-pile manuscripts were — however poorly they may achieve that. Good code can be fascinating.

4. Being able to read code is more necessary than being able to write it, so hiring programmers who can't read code is worse than hiring programmers who can't write code, for the following reasons:

ⓐ If you can read code but can't write code, you can find bugs and figure out how to fix them. Roughly all existing programs have a large number of bugs. So this activity is very valuable, even more so because most programmers are bad at it. By contrast, if you can write code but can't read code, your code will be full of bugs, because you won't be able to see the bugs you just wrote when you look at the code. (Finding bugs in your own code is harder than finding bugs in somebody else's!)

ⓑ If you can't read code, then you don't know what makes code easy or hard to read. Writing readable code is hard; it doesn't happen by accident. So if you can't read code, aside from writing buggy code as mentioned in point ⓐ, you'll write unreadable code.

About point 2: do you read a lot of poetry or math? Because I find that code has a velocity of reading similar to math or poetry. In all three cases you can skim, but not without missing a lot.

I wrote a note the other day on why code-reading is so little practiced; maybe it will interest you.

Leave a comment

About Steven Haryanto

user-pic A programmer (mostly Perl 5 nowadays).