Lab Rat Code

My older son has gone back to school to study IT, and we occasionally discuss his courses or internship (though not his homework). As a graphic artist, musician, gamer, and box-builder, he is an experienced user, but thinking as a programmer is new to him. Therefore I find his perspective on programming an interesting counterpoint to my own:

• I have been programming long enough to have forgotten what seemed clear or opaque when I was a beginner.
• Our backgrounds (artistic versus mathematical) provided different sets of expectations and metaphors.
• He can take advantage of, and for granted, an enormous variety of resources that did not exist when I started, from a wealth of alternative programming languages and open-source code to pervasive consumer-level use of the Internet.

He has also encountered a phenomenon that has frustrated me throughout my time as a student, teacher, and practitioner: lab rat code.

Illustrative code in blogs, articles, and textbooks is often unrealistic for the same reason that physics homework refers to friction-free pool tables and the stereotypical psychology lab is filled with rats and mazes. A writer who wants to illustrate a technique needs to apply it to a task that is simple enough not to create distraction. Stated from the other perspective, a reader who doesn’t understand the goal will likely not appreciate the path.

So the canonical first program in a new language prints “Hello, world!” to standard output, often soon followed by YAFG (Yet Another Fibonacci Generator).

The challenge remains for the reader to ignore distraction. I’d like to offer some strategies that I find helpful in that role.

1. If the sample task seems too trivial, then the author succeeded in picking a goal that doesn’t require much of your attention. Stop reading long enough to sketch out what you regard as the obvious solution, then resume reading to see if the author’s solution offers you any new insights.
2. If the task seems unfamiliar, then the author may have used more detail than necessary. Skim the problem statement, then examine the solution to see how many of those details actually matter for the illustration.
3. If the solution seems too heavy, the author may be illustrating it on a problem that doesn’t require its full power. Check to see whether the author follows up with a harder problem that exploits more of the solution’s capabilities. Or create your own example of a harder problem with similar characteristics. Delaying the natural tendency to think, “I can solve this more easily another way!” may provide an opportunity to understand the reasons for the apparent complexity.
4. Develop a tolerance for uncertainty. I have developed a better appreciation for some concepts only through repeated exposure. (It really doesn’t matter whether that statement is about the concept or about me. The result was worth the process.) Similarly, I have sometimes learned something interesting from a solution to a problem outside my experience or interest. Over time you may develop a sense for what you can safely ignore.

The author who wants to reduce the risk of distraction might consider some of these strategies:

1. Avoid cliches like the plague. Instead of offering YAFG, come up with a fresher example (unless you know your readers really LIKE Fibonacci numbers.) Which brings me to my next cliche…
2. Know your audience. I have heard busy practitioners dismiss a technique because (IMHO) they had never been shown its application to a problem about which they cared. A bill-of-materials example might illustrate recursion to an industrial programmer far better than parsing or binary tree traversal.
3. When using a lab-rat example, be explicit about that fact. At least then your reader will be forewarned.
4. If realism, or an agenda beyond the single example, prompts you to include more detail than necessary for the current illustration, consider the structure of your presentation. Can those details be delayed? If not, than being explicit about which ones are important to the solution may help your reader avoid bogging down on the less relevant ones.

I’ll try to apply those practices myself, both as reader and writer.