The literacy gap in research programming - should we care?

Some things only reveal how deeply complicated they are when something goes wrong and exposes the inner workings. Take for example written communication such as this post: if it works well, then people understand it. But we barely give it a second's thought, because all grownups will be able to read it. The target audience knows the vocabulary. But try to explain this post to a 1st grader, and you will immediately feel all the missing layers of knowledge that are usually there to make it work. Explaining programming culture to 1st graders is rare, but this is not the case in research programming.

See, I go through a lot of effort to make sure that my code is readable, and I do all of the code hygiene that is common practice among programmers: I write nice-looking, well indented code with meaningful variable names; I break it down into logical units that interact wisely (If I say so myself) as much as I can; and I document each interface and function. And yet, even I occasionally hear a fellow researcher say that he had trouble understanding my code. So what went wrong?

There was recently a discussion on Slashdot that demonstrates the underlying effect. It revolved around reading code - aloud. Some people said that they read the words aloud and the symbol names too. for example, "if (i == 5)" they would read out as "if i equals-equals five". Others, who turned out to be more exerienced, would read out a more simplified version, where the interpretation is mixed into their words. "if i is 5" or even "if the TLA algorithm was chosen", assuming they know that in this code, that is the meaning of i==5. It turns out that the more your head is holding advanced concepts, the more you can identify them in writing and see the concept, instead of the constituent letters.

Exactly the same thing happens when people learn to read. My nephew was still reading letter by letter a year ago, then started reading syllable by syllable, and can now identify words. If you go further down the scale, to grownups, you'll notice that you can read text and describe the ideas in it without ever remembering one actual written word. your brain skipped it. Indeed, if our brain did not encapsulate ever more complex constructs into ready-to-use idioms, terms and imaginary concepts, we would not be able to get any grown-up work done.

The same things happen to experienced programmers. when a beginner would think about how to write a loop, keep an index counter going and use it to access each element in an array in turn - an experienced programmer would just say "I need to iterate over this" and the code will flow automatically. And the things that makes this a pitfall for understanding, is that nowadays programming languages are ever more expressive. They let the programmer express her concepts rather than tediously explain how the hardware will execute it. This has been going on for a long time now. From pure machine code to Assembly languages, then HLLs (C, C++, Java, fortran) and VHLLs (Python, Perl, Yorick), the level of abstraction you can use gets higher and higher.

And here's the difference from reading and writing. In academic circles you will always write to people at roughly your writing level. But programming experience ranges from almost none (a basic course from 1st year) to much experience with no training, and very few have both the experience and the training. This makes the situation of "explaining to a 1st-grader" quite common and even essential.

It is tempting, as a team player, to solve this by writing to a 1st-grader. But this temptation has a cost in expressiveness, and therefore productiveness. I used to teach my late Grandmother how to use a word processor. I would then feel how hard the most basic operations can be, and I would get mad at the GUI designers for not making it simpler. But then I realized that designing an interface for someone with a neurodegenerative condition essentially comes at the expense of the rest of us. I can be sad for those having the condition, but it would be wrong to demand that everyone else give up their productivity just to serve this small group. The same should be true to programming: sometimes it's good to express yourself at your language even at the expense of requiring more efforts from others.

The trade-off between accommodating the team and being productive should be decided on a case by case basis. There is also one thing in favor of expressiveness in academic code: if you are not many levels more expressive than your reader can understand, you could actually help him learn to express more complex code in a concise and efficient way. So there is some sneaky optimum, and we should search for it, rather than fully "dumbing it down" or conversely, giving up on communicating through code entirely.

Well, communication is just like Paul Simon said about love: the only time that it's an easy game, is when two other people are playing it.