allenc allencheung

Understanding Code by Transcription

As most programmers know, as systems grow in complexity, more time is spent reading rather than writing. Enhancing a body of code, fixing bugs and issues, refactoring and moving pieces around, or simply just using a library or framework all require reading and ultimately understanding how the code works.

Well, sometimes. In this day and age where Stack Overflow and jsFiddle exist for code snippet requests, there’s less emphasis on trying to thoroughly walk through a piece of code versus just selecting the block, ⌘/Ctrl-C, then ⌘/Ctrl-V [1]. However, I’ve found that more often than not, it’s very useful to read through a piece of code; even if I’m just the consumer, truly understanding what’s going on while writing my code helps avoid headaches and obscure bugs onward.

The problem is, reading code is boring, so I borrowed a technique from memory and cognition: type out the code.

One of the techniques suggested for memorizing a passage is to type it out in full. The idea is that by writing out the full text (instead of merely reading it), I’m forcing myself to spend more time going over the text, and at the same time I’m making myself understand the passage instead of reciting the words. I’ve heard the same idea being applied to understanding a piece of literature, as well as studying for an exam by writing down a cheat sheet (which may never be used).

That is, the act of writing seems to trigger a deeper connection with the text and its content, both in recollection and understanding. So I apply the same idea to coding[2].

When looking to use a piece of code that I know I’ll need to understand, I flex my fingers and hunker down to type out the snippet in full, as long as the code isn’t overly epic. For one, it forces me to slow down and think about what the code is actually trying to accomplish: I know where variables are being initialized, loops being broken or continued, and with a little bit of work figure out where the magical recursion happens. I’m not jumping from line to line tracing through function calls, but with most decent code functions are well-abstracted and still make sense when read linearly.

Typing out the code by hand also lets me correct formatting errors along the way, as well as refactor lightly, fix typos, and make tweaks to integrate the code into the rest of the system. Plus, when I type something that has an unfamiliar manual feeling – e.g., using (x === y) over (x == y) in Javascript – I get an opportunity to learn from someone else’s coding style.

And if nothing else, rote code transcription is manual labor which lets my mind take a break from keeping the state of complex abstract systems in my head, while maintaining (reduced) productivity and keeping me in the zone.

Unfortunately I’m the only person I know of who does this. Am I doing it wrong, or do other people have different and better techniques for reading code?

Footnotes    (↑ returns to text)

  1. Or if you’re more terminal-oriented, Ctrl-Ins and Shift-Ins.
  2. It also helps that I type reasonably quickly.
By allen
allenc allencheung