Readability And Scannability

I distinguish quite strongly between “readability” and what I call “scannability”.

I think that our trade’s pedagogues, even our very good ones, conflate the two, and in so doing inaccurately describe programming and ineffectively prescribe remedies.

Maybe the way to approach the idea is through your experience of seeing. Humans — most vertebrates, in fact — rely heavily on "seeing". The fabric of our experience is richly visual. A large portion of our neocortex is given over to it. Its use as metaphor is ubiquitous.

(Age 12, I had an older uncle-figure, blind from birth, was telling him about something, and I said, “See how it works?” Then I realized to my adolescent horror what I’d just said, fumbled & apologized. He laughed. “Relax, kid, I know what you meant, I *do* see how it works.”)

Our visual experience looms large. And most of us carry around a straightforward concept of how it all works.

“There’s a reality. Light strikes it and bounces into my eye. My eye has a simple grid of receptors. It sends that to a grid of nerves, like a photo. I have direct access to the photo, I peruse it as, when, and how I want. My visual experience is mechanical, direct, and raw.”

This concept of my visual experience is appealing. It’s simple, it’s logical, and it makes it very easy to think about seeing. And don’t get me wrong, it has a modest amount of “truthiness” to it. But it’s not really what we do when we see.

Basically, that entire story is filled with “exceptions” and “yeah but’s”, and “corner cases”, and “appoximations”, and “true but misleadings” and even “trivially incorrects”. So many of them, to be honest, we’d be here all day trying to list them all.

For the purposes of approaching “readability” vs “scannability”, there are two particular categories of things that are misleading about that visual experience concept. The first is about how “raw” it is. The second is about how “passive” it is.

Far from being raw, your visual experience is one of the most “cooked” things about you. By the time you became aware of what you see, in an extraordinarily complex and astonishingly beautiful organic parallel process, it’s been retouched so much as to qualify as a deep fake.

Color has been guessed at. Lines have been straightened. Distances have been estimated. Face-like shapes have been magnified. Broken figures have been mended. Things getting larger are amplified. Whole clusters of shapes are coalesced into chunks. Holes have been filled in.

Further, all that retouching isn’t “context free”: that process doesn’t do the same image manipulations the same way every time. On the contrary, it is heavily influenced, very nearly “driven”, by the state of the receiver’s attention.

“Seeing” is an active process. What one expects to see can dramatically alter what one actually sees, well below the level of your conscious agency.

This isn’t fringe science . We have thousands of demonstrations of all this. They range from trivial-seeming optical illusions to incredibly detailed experimental data. It, by the way, is a lovely hobby study, sure to appeal to anyone with the least affection for science.

We only partially understand how it works. But one thing we can say with some authority: it doesn’t work the way that naive model above says it does. It is not remotely raw, and it’s cooked not only by passive automatic processes but active attention-driven ones.

When I say “readability” vs “scannability” in the context of programming, I am suggesting that readability is like the naive model.

If we have a stable artifact, like an actual photo, we can and do “read” it. We take our time, examine each area. We can share it between ourselves. We can magnify part of it. We can use our conscious agency to direct how we work with it.

We can do all that, not only with a photo, but also with a program text. It is always possible to do that. But that is not what we do most of the time when we’re manipulating the text of programs. There, what we do is like what we do when we “see”.

Sit next to a hardcore geek, someone you think of as one of the best, and watch how she works, and it will become readily apparent how little of her time she actually spends “reading”.

I know you’ve seen this, maybe even you do it yourself. There’s 25 open windows. She’s hotkeying around. She moves so quickly that if you’re remoted through a vpn, the screen-sharing software can’t even keep up.

There are really only two possibilities. Either…

  1. She reads program text many times faster than you read *anything*. Or…
  2. She’s not reading.
I, obviously, contend that what she’s doing isn’t reading. She’s scanning. She’s detecting features, she’s directing her attention, she’s doing all the things we just discussed in that long discursion about how actual seeing works, as opposed to our everyday naive model of it.

All programs that compile and run are “readable”, because compilers and interpreters don’t compile and run code any other way than to examine it, first one character, then one symbol, then one line, then one statement, and so on, at a time.

Programmers, on the other hand, don’t experience code that way for the most part. They, instead, use lots of cooking and lots of directed and active mechanisms to work with code.

When someone tells me that a weak variable name is okay, they nearly always invoke the fact that, since we’re all reading the code, it does no harm. Long functions, same. Large classes, same. Poor encapsulation, same. Leaky abstraction, same. On and on.

Many people have told me that none of that matters, that a long text is as readable as a bunch of short texts. That an arcane fragment is as readable as a simple one. That an inline complex conditional is as readable as an extracted & named one.

And they’re right.

But “reading” code isn’t mostly how humans “see” code, anymore than “reading” photos is how they “see” the world.

And why not? Because it’s way too slow.

Real programmers really programming do certainly read code sometimes. But mostly they do that other thing. And any change I can make in the text that makes it easier to do that other thing improves my efficiency.

I will even go so far as to recommend that we optimize our code for scannability.

Here’s a video that makes that point:
Optimizing A Program (And Programming) | Video | GeePawHill.org

So, anyway. As I say, a lot of great programming teachers still use the “readability” concept. And I’m not ranking on them for it: I am generally quite aligned with their views about what makes things more readable. But I prefer the term “scannability”.

I’m gonna go scan me some kitchen now, cuz some of my other senses are suggesting to me that it might yield pleasing results if I pay some attention to what they’re doing down there. 🙂

Y’all have a pleasant evening!


GeePaw Hill

GeePaw’s Camerata is a community of software developers leading in changing the industry. Becoming a member also gives you exclusive access and discounts on the site.

The GeePaw Podcast

If you love the GeePaw Podcast, show your support with a monthly donation to help keep the content flowing. Support GeePaw Here. You can also show your support by sending in voice messages to be included in the podcasts. These can be questions, comments, etc. Submit Voice Message Here.

Want new posts straight to your inbox once-a-week?

1 thought on “Readability And Scannability”

  1. I love the guidance for writing good code. How much and what form do you recommend as architecture and design documentation besides readable and scannable code? I was thinking a lot of it would be readable and scannable TDD and BDD tests. My teams recent results are that the test-driven unit tests and the BDD tests are haven’t turned out to yield scannable and readable info about the design. Before I launch an effort to refactor the test code to be design documentation I’d like to know if you think it’s possible and advisable.

Comments are closed.

Scroll to Top