How to Read Other People’s Code — and Why

If you are a professional software developer, or aspire to be one, you will need to know a lot of of things. Various maths, stats, languages, frameworks, methodologies, tools, etc. Fads and buzzwords will come and go, all during your career. You’ll master some, ignore some, laugh at some.

But aside from the desire and ability to work in abstracts for concrete results, there is one skill that is an absolute must-have.

You have got to be able to read other people’s code.

Reading other people’s code is hard graft. Few young developers look forward to perusing other folks code, to mapping out the functionality, to learning the ins and outs of how it works.

But it is absolutely necessary.

We’ve all been there: faced with a mountain of code (which, by the way, is currently working in production) written by the guy who left, the girl who is on vacation, the guy whose wife is having a baby, who is on his honeymoon, who has won the lottery. The boss needs a new feature added or a bug fixed, and you’ve never looked at the code.

But you’re on the hook for it. What to do?

The essence of reading code is fairly simple: build a reasonable mental model of the code in question. If you have a working model of how the code works, you can make changes with some expectations as to how it will react. There is no magic bullet; it is sometimes harder to read and understand code than to write it in the first place. Here are some approaches that can pay off:

First — Do No Harm
This is a simple prohibition against common temptation. Go ahead and add logging code, maybe some stats recording, etc. But test rigorously to ensure you don’t change how the code works; understanding working production code is hard enough without mutating its behavior. This prohibition also includes resisting the temptation to “just write it from scratch” yourself. Bad, bad idea to do so under the gun, with a deadline, in a domain your not expert in. And if you haven’t written code for the problem domain, you are not expert in it.

Unit Tests — Use’em if you Got’em
Unit Tests are wonderful if they exist. Twenty years ago, they were rare in software — nowadays they are much more common. If you have them they are the best, truest documentation of how the code works. Start here, play here, make changes to the unit tests and observe what happens, take notes, learn all you can. Try to write some new tests to test your understanding. This is your chance to poke and prod at the code and observe how it responds. Think of Unit Tests as the petri dishes of software lab research.

And if there aren’t any Unit Tests, write some.

Read the comments, but don’t believe them
This goes for design documents, requirements, user stories, etc. Code documentation has an aging component to it, and artifacts like design documents are rarely representative of the code. Comments are “younger” in some sense, but we’ve all seen tons of comments that make no sense. So read the comments and such, but think of them as archeological hints at best. They tell you what the code might have been trying to do, sometime in the past.

Make a separate model of the code
This is the goal of reading the code in the first place, but here I mean make a real model. On a whiteboard, with a mind-map, on a pad of paper, with small action figures, I don’t care. But make a model of some sort. Seeing it outside your head in some form will help you firm it up and point out wholes.

Don’t Hate the Code
You can get sucked into hating the code, merely because it is not yours. Software people tend to be equipped with ample egos, and other people’s code can offend. But realize, their working code is better than your imagined code, because their working code exists right now. So put your ego aside and learn the code in front of you.

There is an important but oft-overlooked point to keep in mind when looking at other people’s code: the folks who built it the first time had a model for it, and it made sense to them. Respect them enough to look for that model. I will concede some peoples’ minds work in strange ways.

Reading other people’s code can be an overlooked skill in these days of rapid prototyping, shoestring start-ups, and hero coders. But you’d be well served to learn to read code. One might diffidently point out that the much of the open source software movement (is it a movement?) requires you to read other people’s code.

Learn to read code quickly and well; it’ll make you a better developer.

Update: this turned out to be my most popular post ever. I completly attribute this to me writing it while at Strange Loop 2009 in St Louis. Great conference!

Explore posts in the same categories: Tech

Tags: Artisan, Design By Gravity, Software Development

You can comment below, or link to this permanent URL from your own site.