Should We Talk To Ourselves When Reading Code

On "HowToTalkToYourselfWhenReadingSmalltalk", you'll find a portion of fairly simple Smalltalk code that is fairly difficult to read in English.

There are a few examples of how it could be read in English. One person to submit an example was RonJeffries, who ended up concluding with, "Strictly I don't think those thoughts. I see that code and for most lines I just know what it means. I don't translate it to English to understand it, just as I used to not translate German to understand it, and as most of us don't translate our "native" programming language"

Something else to throw into the mix: A basic speed reading technique is to stop reading things aloud in your mind. Reading like that arbitrarily limits you to the speed that you speak.

So, the question is this:


The talking-to-myself that I do while reading code tends to consist of summarization ("It looks like this part searches the list for the desired element, then this part processes it, and this part writes the result to a file."), criticism ("Why didn't he use the standard list class?" "Will this blow up if X is negative?"), and appreciation ("Hey, that's nice. I should steal that idea.").

I disagree with the opening assertion on this page that the example in HowToTalkToYourselfWhenReadingSmalltalk is "fairly difficult to read in English". I am a rank amateur when it comes to Smalltalk, but I find the example very easy to translate to English or to other programming languages. In just a few seconds, my mind translates it to "Return a new collection containing each element for which aBlock evaluates to true". The temporary variable and the specifics of Smalltalk syntax and collection-processing idioms disappear.

Different people may translate it differently, but that does not mean it is not easily translatable. As with spoken-language translations, the trick is not to try a word-for-word (or symbol-for-symbol) translation, but instead to determine the meaning of the entirety and then re-express it as clearly as possible in the other language.

This is a skill that takes time to develop. After using dozens of programming languages over the years, I tend to ignore syntax and other "noise" when reading code, and just try to get the gist of whatever the programmer was trying to express. New programmers may not be able to do this, because they don't think like other programmers yet, they aren't familiar with the common idioms, and they don't know what is unimportant enough to ignore.

Well-written code generally can be "spoken" easily, but does not need to be. In other words, it is clear enough that it can be trivially translated to English, but also clear enough that translation is not necessary.

Of course, one must read more closely when tracking down a bug or when one intends to modify code. Mental translation to English (or whatever native spoken language) is helpful in these cases. When it gets to really low-level details, I tend to translate code not to plain English, but to a sort of "pseudo assembler" where I think about registers, memory locations, primitive operations, etc. for an imaginary virtual machine.

-- KrisJohnson
Yes, we should talk to ourselves when reading code. Not all the time, but when we need to engage the maximum number of neurons. Most of our symbolic processing is associated with speech and hearing. -- EricHodges

EditText of this page (last edited January 6, 2005) or FindPage with title or text search