Code by Number replied frighteningly quickly to my previous article on code spelunking with a totally obvious suggestion:

What was missing, I thought, was the easiest one of all: Draw a picture.

Ha! Absolutely right. Even more ironically, I actually have a notebook sitting in my lap with a half-drawn picture of the thing I’m working on right now that spurred the article. I guess it was too obvious for me to see… :)

I concur with the suggestion to draw the picture by hand on a piece of paper. For one thing, it let’s you be as flexible as you like (easy to add notes, draw crazy lines, cross stuff out, etc). Whatever you do, don’t use a formal UML modeling tool – they are way too rigid for this kind of exercise. Paper is better than whiteboard due to its persistence and also as its easier to do while looking at the code.

Also, there is crazy stuff that goes on in your brain when you do something physical – you will remember something drawn by hand much better than something “modeled” on a computer. Or at least that’s been my experience. One quick drawing by hand can beget much better drawings on the computer later.

Here’s an example of a writeup I did initially on paper then later formalized into pictures and description for future spelunkers.