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"
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.
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.
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.
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.
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:
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.
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
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 each important function to see what arguments it is getting called with,
and to get a general idea of the control structure.
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
When all else fails, read the documentation.