2000/05/26

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.

About the author.

In 2000 I co-founded Fog Creek Software, where we created lots of cool things like the FogBugz bug tracker, Trello, and Glitch. I also worked with Jeff Atwood to create Stack Overflow and served as CEO of Stack Overflow from 2010-2019. Today I serve as the chairman of the board for Stack Overflow, Glitch, and HASH.