[A picture of private offices at Fog Creek Software] Alert! This ancient trifle retrieved from the Joel on Software archive is well-past its expiration date. Proceed with care.

Joel on Software

2000/05/26

by Joel Spolsky
Friday, May 26, 2000

Seth Gordon emailed me some great tips for reading other people's source code. Reading Code is Like Reading the Talmud

Ramon Garcia Fernandez writes:

In your essay 'Things you should never do, Part I' you are against rewriting source code. But, what if the author of some source code is not available? What methods would you recommend to understand code written by another programmer? This situation is often encountered in the free software world, where you would rather reuse an existing program than write one from scratch, but it is difficult to read code written by another programmer.

My response:

I think the best way to read somebody else's code is just to SLOW DOWN... it's like deciphering a code, not like reading. Most people have trouble reading code because their eyes are used to reading at a certain speed from reading text written in human languages. But code is much more dense than English, and contains 'secrets' that need to be deciphered by looking elsewhere: for example, when you see that function call that says UpdateData(FALSE), unless you remember how UpdateData() works, you have to go look for it to figure out what the first argument is and what FALSE means.
It takes some skill to learn how to read code slowly and carefully, and many programmers are not patient enough (so they wind up rewriting the code from scratch). But you have to remember that it's still faster to read than to rewrite!

While we're at it, Lou Montulli, one of the founding engineers of Netscape and the creator of Lynx, sent me the following response to my plea never to start over from scratch in 'Things You Should Never Do':

I agree completely, it's one of the major reasons I resigned from Netscape. In 1998, after wasting a year wanking, a group of new but experienced programmers, and one of our misguided founders, decided it was a good idea to rewrite everything. I had alot of vested interest since I had done most of the original design work on Navigator, but I was unable to supply enough visions of doom to divert the effort. The original design had degenerated substantially due to the integration of Java and the rapid pace of zig zag development that went on over the course of 4 years. There was good reason for a large change, but rewriting everything was a bit overboard to say the least. I laughed heartily as I got questions from one of my former employees about FTP code the he was rewriting. It had taken 3 years of tuning to get code that could read the 60 different types of FTP servers, those 5000 lines of code may have looked ugly, but at least they worked.

Alfie Kohn: While rewards are effective at producing temporary compliance, they are strikingly ineffective at producing lasting changes in attitudes or behavior.


Have you been wondering about Distributed Version Control? It has been a huge productivity boon for us, so I wrote Hg Init, a Mercurial tutorial—check it out!

Want to know more?

You’re reading Joel on Software, stuffed with years and years of completely raving mad articles about software development, managing software teams, designing user interfaces, running successful software companies, and rubber duckies.



About the author.

I’m Joel Spolsky, co-founder of Trello and Fog Creek Software, and CEO of Stack Exchange. More about me.

© 2000-2014 Joel Spolsky