How I Write Code: Pen & Paper


I am a self taught programmer. I first started programming as a kid, and have never bothered to formally study this discipline. To me, programming is first of all a pleasant creative pursuit. It’s a bit like putting together and taking apart all kinds of machines, except these machines happen to be virtual constructions, and you get to keep your hands clean (well, mostly…) Incidentally, this pleasant activity is also how I support my family.

But even though I love programming, I try not to sit in front of a computer screen too much. I do not find staring at a screen all day beneficial, not for my physical health, nor for my mental health. In the last few years, I’ve started a habit of sketching my programming ideas using pen and paper. I’m not talking here about todo lists, or making diagrams. I’m talking about actually writing code using pen and paper. Let me explain.

Why pen & paper

A lot has been written about the advantages of handwriting vs typing. I will not enumerate all of them here, but I will tell you that since I started this practice I find I’m more productive, and I seem to produce better-quality code.

The mere fact that I can concentrate on a single problem without any distractions is already a big advantage, and it seems to me that through writing pages upon pages with a pen, scratching bad ideas, rewriting small bits of code, I gain (as if by magic) a deeper understanding of my code.

What about debugging? What about testing?

When you write code on paper, you have no way to see if your code works. Maybe someday I’ll be able to handwrite code on an e-Ink device and then run it. Until that day, all that I have is my ideas, my intuition, my knowledge, and my “mental runtime” - a mental thought process that simulates some kind of computer runtime that goes through the code, evaluating it.

Of course, my mental process is not perfect. It will let slip through all kinds of bugs, things I’m not smart enough to detect before actually feeding the code to a computer. That’s why I try to concentrate on one small problem at a time. Nothing bigger than a page or two, and mostly short snippets that implement a specific algorithm.

Iterate, iterate, iterate

So once I start exploring a problem space with pen & paper, I just iterate on it until I feel I’ve found the best solution to the problem. Once I’ve achieved that, I can finally open my laptop and type the code into my favorite editor.

Sometimes it works like magic, I just type in the code and everything works. Sometimes it needs some additional effort in editing and elaborating. But still, even if my handwritten code turned out to be only partially correct, or needed some reworking for it to fit in with other components, I feel like spending time sketching code and reflecting on it before turning to the computer has given me a deeper understanding of the code.

A recent example

Here’s an example of coding I did completely with pen & paper: a few days ago I published a new open-source project called Ever - a libev-based event reactor for Ruby. The entire design was done with pen & paper. I did it over three evenings, taking a couple hours each evening to work through the design and different aspects of the implementation.

Finally, when I felt the design was solid and that I had resolved all the issues I could see, I opened my laptop, created a new Github repository, typed in the code, added some tests and wrote the README. It was probably all done in 4 or 5 hours of concentrated work.

At the end of the process, in addition to being able to create a small Ruby gem in a single day without too much fussing around looking for solutions to problems encountered during development, I feel like I have a deeper knowledge of the code, a deeper understanding of the implications of different choices, and a greater appreciation for writing the least amount of code.

When I hold a pen in my hand and set it to paper, I find it much easier to be “in the zone”, and I feel much closer to the ideas I’m exploring. Somehow, I never get this feeling of connectedness when laying my hands on a computer keyboard. It also empowers me to know that I don’t need a computer in order to create code. I’m not dependent in my creative pursuits on a machine that sometimes seems to disturb my creative process rather than facilitate it.

Steve Jobs once talked about computers being like a bicycle for our minds. To me it feels like a lot of times we expend lots of energy on bikeshedding rather than actually riding our bikes. And maybe we should also get off our bikes every once in a while, and just walk.