Code Formatting Conventions

I have vague (and probably inaccurate) memories of an article I read maybe 25 years ago. Please remember that every remembered “fact” is probably wrong…

Some time in the ’80s, Adobe (or some company) did extensive studies to figure out what makes text readable. They looked at the font, the size and style, character and line spacing, line length, foreground & background colors, etc. The fact that stuck in my head was that yellow or green text on a black background could be read 30% faster than black text on a white background. Wow! That’s a huge number. If I could code 30% faster, I think that would justify a 30% raise.

This was about the time that “Paper White” displays were just starting to become affordable, and everything started using white backgrounds, including the latest version of the editor I used at the time. I actually had to turn down the brightness on my monitor because it gave me headaches. The Adobe article made me think, though… Sure, paper is white, but my monitor isn’t a piece of paper. All the cool people are using white backgrounds, but I’ve never been very cool. What if I used a black background…

I changed my editor’s settings to use yellow text on a black background. The difference was amazing. I don’t know if I could code 30% faster, but my head ached at least 70% less. (I’ve spent the last 25 years wondering why anyone uses black text on a white background for anything. I’m sure you’re wondering why this post is black on white. I’m wondering the same thing, but that’s what WordPress defaulted to, and I haven’t wanted to spend the time figuring out how to change it.)

So the question recently occurred to me “is there an objectively better way to format code?” It seems like there must be. There may not be a style which is better for every individual, but there must be a style which is better on average.

When Adobe did these studies, doing something like that was a fairly expensive undertaking (at least I assume it was). I picture them getting thousands of people to come in, read some piece of text (while some guy in a lab coat times them), and take a comprehension test. They probably had to pay the people something for their trouble. They had to pay a bunch of guys (working in parallel) in lab coats to sit there with a stopwatch. They had to pay someone to recruit test subjects. They had to pay someone to grade the tests and interpret the results. They had to pay for office space and coffee and who knows what else.

The Internet changes all this. I don’t have to recruit you or pay you. You don’t have to come to my office. I don’t have to sit around with a stopwatch. Heck, I don’t even have to buy a lab coat. All I have to do is convince you (and a few thousand other people) to spend some time taking my little quiz.

I should rephrase that last bit. All I have to do is decide what makes a formatting convention subjectively better, and figure out how to measure that, and create a quiz that does measure it, and then I have to convince you to take my quiz. Fortunately, I did those other parts before writing this blog post.

What makes a formatting convention objectively better? I think it’s nothing more than the speed at which you can read and understand unfamiliar code. Speed is important – you can understand anything if you spend long enough. And if unfamiliar code is more clear to you, then your own code should be clearer, too.

Take the quiz!


My quiz has been available for a little while now. I don’t have enough data for the result to be statistically meaningful, but the data I have is very suggestive: Yes, code formatting affects understandability. The effect is dramatic. Thirty percent raise, here I come! (Unless, of course, the effect disappears when I get more data…)