Learning to Read and Grok Other People’s Code

One reason many people don’t contribute to open source apps is because they find it daunting to look through somebody else’s code. Some might even think that it’s just simpler to write something from scratch than to study someone’s work. This isn’t true, and reading foreign code is something get used to and excel at over time. It’s a necessary skill for every programmer, and has many benefits.

A huge benefit is the massive amount of information you learn and get accustomed to in a short period of time. There’s no way to download O’reilly PDFs into your brain just yet, but grokking source code written by those much more experienced than you is one of the fastest ways to see and practice everything you’re been learning in theory (books, sites, classes).

It’s certainly overwhelming to jump head first into a huge app trying to understand every line. I think it’s common for people to open up some code, read it for a few minutes and then never touch it again because they don’t understand it. This was the case with me when I began programming. Here are some ways i used to justify putting off the need to read third party code.

Their code style didn’t suit my taste, i.e., they add the opening curly bracket under the function definition, and I would find myself changing their brackets and formatting more than I spent time actually looking at the logic.

I told myself I would learn much more by re-inventing the wheel, or have more control over my app if I built it from scratch. This is only partial true, but the cons outweight the pros. Reinventing the wheel means diviating from writing program logic and having to learn something that might not even remotely be related to the project I intended to start or finish. Here’s an example that used to be common.

I would happily hack away and then realize that I need a string library (I <3 C). At this point I could have downloaded one, and continued hacking at my app. But instead I would start a new project aimed at writing an efficient string library. Before I knew it, I’m hours into my string lib and totally abandoned my main project. I usually¬† anyway. The funny thing is that sometimes I’ll just give up and use a third party lib, but most of the time I just ended up scrapping both projects. What a waste of time.

Everyone has their own way of learning other people’s code. I found that what works best for me is to download an app and just browse the source indifferently. It’s not good, it’s not bad, it’s not ugly or inefficient or godly. I just try to get a basic idea of where everything is, what plugins are being used, etc. Layout stuff is in this general area, settings here, plugins are all in there, etc. This step is probably useless and I only do it as a guilt-free way to avoid working for 10 minutes. Or, maybe it does help.

Then I begin by setting up the environment. Put in my DB settings, make sure I have all the requirements installed, etc. Logs are your best lead at this point. I usually open up a fullscreen console and tail -f the log file(s), then watch them like a hawk every time you shift a pixel in the code. It’s not as tedious as it sounds.

Another thing that helps is knowing the language/framework the code is written in. You should know at least how to read the language – though if you’re dedicated, I’m sure you can muddle through with a crash course/reference sheet. By knowing the lang/framework, you can find or create some functions to help you debug and examine objects (even just raise object.inspect is great) in detail. You can also examine other aspects of the code. One thing I do early on is rake routes > ROUTES. This saves all the routes to a file which I can glance at if necessary. And rake routes takes forever on my ancient machine.

After this, the code is compiled/started and I’m ready when I can interact with it live. Now I begin actually reading the code. If I have a specific update I want to make, be it adding a new feature, fixing a bug, or seeing how something works, I work backwards from the live app tracing everything going on around the component I’d like to edit/update.

This is not easy, not quick, and very error prone when you’re making updates. Things breaking == You learning, and all you need to do is be persistent. It’s like reading a calculus book. Nothing will make sense until you turn over the page and see how the problems and answers are laid out, and begin doing them on your own. It’s a great feeling when 2-3 days later you realize that you have a pretty good view of the app’s design (unless it’s something like the Kernel).

No matter how cryptic the code looks, don’t be turned off. Is there some sort of force that will completely stop you from understanding what the logic says? Can other people look at this code and instantly tell you what it’s doing? (well, they can form a great guess if they have the experience). It’s time consuming but the concepts apply to other things in life. You can understand how to change your oil without knowing how the engine works, or how to make simple CSS/HTML changes to a layout to change the background or font size without knowing every single CSS tag and technique.

define:persistent: Refusing to give up, especially when faced with opposition or difficulty; continuing firmly or steadily

Most of my favorite quotes are about it. It’s unfortunate my memory isn’t very persistent.

persistence poster

Do you have any special techniques/advice for learning to read third party code?

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>