4.889 Intelligent Interface Software Design Workshop

Reading Somebody Else's Code

"Oh, no! In 4.889 they just dumped this whole huge pile of code on us, and they expect us to read and understand the whole thing right away"

Don't despair!

I know it seems like a lot, but you will often find yourself in a similar siutation where you may have to understand a large body of code that you didn't write. You'll find good code-browsing skills valuable. Here are some heuristics to help you.

Code is not like a novel

First, don't be tempted to read the code like a book, starting at the beginning and reading cover to cover. Actually, you might want to skim the whole thing at first just to get a rough overview, but if you insist on understanding each and every thing before you understand the next, you will be lost for sure.

Let the machine help

The trick in understanding a large piece of code without spending a lot of time is to get the machine to help explain the code to you.

Take the time to learn and use the stepper, trace, inspecting and browsing tools. A good Lisp implementation will have excellent tools that will make the job a lot easier. Many important relations in a program are non-sequential, and there are tools that will help you find what to look at next.

Start with an example

Don't try to understand what all the code does at once. Instead, start with a specific example, representative of what a new user might try in his or her first session with the program, or an example from the manual primer.

Set yourself the task of learning just how that particular example works. Ignore everything else that doesn't pertain to that example.

Go just as deep as you have to do to understand it, no deeper. Treat everything else as a black box. Learn about how it works later.

Become familiar with the user interface from a user's perspective. For each user-visible action or object, ask: "Where is that implemented"?

Have a specific goal in mind when you work. Experiment with small changes and extensions to the code to test your understanding.

If it ain't broke, fix it

The best attitude to take is to pretend you are debugging the code, even if there is nothing wrong with it. The same tools that are used for debugging the code will be helpful in getting you to understand it in the first place. Even if you aren't looking for bugs now, if you plan on using, extending or modifying the code, you soon will be.


Here is a quick overview of tools to help you understand unfamiliar code:

Jump to function definition

The most important tool in most systems is a keystroke in the text editor that takes you to the definition of a function when you point at a call to it. In Macintosh Lisp and Emacs-Lisps this character is Meta-. [Meta-point]. You can then start with the top level function, examine its subfunctions, then the subfunctions of those, etc.

Step the code

The best way to see how a function works is to try it in an example and use the stepper to step through the code. Unfortunately, steppers in most Lisp implementations have poor interfaces, poor level of detail control, and don't work well with user interface code. The interface of the stepper may clash with the interface of the program. This tool is not as useful as it could be in most implementations, but there's nothing better for really seeing how the code works.

Guess function names

If you don't know the name of a function that implements the functionality you are looking for, guess. Use apropos to find all the functions whose name contains that string. If you're looking for the function that draws a rectangle, do apropos on "rectangle".

Trace functions

Trace each important function to see what arguments it is getting called with, and to get a general idea of the control structure.

Inspect the application's data structures

Create example application objects and use the inspector to poke around in the data structures. This will give you a good idea of what the functions want as arguments and produce as values. Especially important in object-oriented programs.


When all else fails, read the documentation.