Thread by @GeePawHill

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:

geepawhill.org/2018/02/02/opt…

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!

Folks, I made a camerata for folks to work on the shared problem of how to change the software trade, including little things like this, but big things, too.

geepawhill.org/camerata

The first 50 yearly members get a free coaching session with yours truly.

Join us today!