Jon Aquino's Mental Garden

Engineering beautiful software jon aquino labs | personal blog

Tuesday, March 13, 2007

Reading code aloud

When reading a programming book, it can be tempting to skim the code examples. But they likely have some nuggets that are worth learning. The problem is that we don't like to read code written by other people - or at least it doesn't come naturally to us. What we need is a technique for rapid understanding of new code.

I propose reading the code aloud. Now, to make sure we don't get distracted by syntactic details, we can probably come up with some rules for what to omit. Consider this example from Martin's Agile Software Development:

#ifndef GEOMETRY_RAY_H
#define GEOMETRY_RAY_H

class Ray : public LinearObject
{
public:
Ray(const Point& p1, const Point& p2);
virtual bool IsOn(const Point&) const;
};
#endif

I would read this aloud as follows:

class Ray, extends LinearObject
Ray p1, p2
IsOn Point, returns bool


So we have a first cut at a rule of thumb for things to skip:
  • start and end matter (e.g. ifndef, define, endif)
  • access modifiers (public, protected, private)
  • parameter types
We also see a couple of transliterations (text transformations):
  • in C++, read ":" as "extends"
  • in function declarations, read "[type] ..." as "... returns [type]"
A more enterprising reader of code could expand or revise these rules and we could have, say, 10 tips for reading code aloud, for maximum comprehension.

2 Comments:

  • An excellent idea Jon. Perhaps with practice using this technique one can learn to "speed read" code by vocally skipping all of the unimportant details.

    Of course, it makes me wish that it wasn't necessary to transliterate so much in order to get to the gist of what a piece of code is doing. I have always had the dream of a programming language where the actual code is embedded in the algorithm's presentation. Hmm, souncs like JavaScript.

    Larry Becker

    By Blogger Larry D. Becker, at 3/15/2007 9:49 a.m.  

  • Hey Larry - 3 cheers for JavaScript! It's a surprisingly malleable language - reminds me of Ruby and Smalltalk - closures are quickly created and easily used and passed around.

    By Blogger Jonathan, at 3/15/2007 9:51 p.m.  

Post a Comment

<< Home