What is code readability, really?

Ka Wai Cheung
On Building Software
2 min readAug 22, 2024

--

I’ve recently started using Ruby on Rails on a side project. I’ve been following its maturation since its very beginning and have always wanted to use it.

One of the core selling points of Ruby is its readability. A simple line like this in my native language C#…

if (!published) {
markAsPublished();
}

…can be expressed in Ruby as something like…

mark_as_published unless published?

I’ll admit, it is pretty. It is quite elegant. It reads like pseudo-code—something a programmer and non-programmer could understand.

I just don’t know if it’s more readable.

Don’t get me wrong. I like it. I’ve gotten a kick out of writing code like this. It feels neat.

But again, I just don’t know if it’s more readable.

The readability of code is not the same as the readability of prose. They are fundamentally different kinds of reading.

Beautiful prose takes me on a linguistic adventure. I appreciate the juxtaposition of a long sentence that builds to a crescendo followed by one that stops just when it was getting started. I like the surprise of how a certain sentence ends. How a mystery is revealed. How words flow off the tongue.

I do not value these things with code. Beautiful code is banal. Expected. It relies heavily on indentation to evoke meaning.

I read prose to be entertained. Held in suspense. Surprised. Even lost at times.

And Ruby has a lean toward that kind of prose. Because mark_as_published unless published? does, in fact, hold you in suspense for a second. It unveils the criteria after the action. A readable prose.

I read code to confidently know what it’s doing. I don’t want the suspense.

Fundamentally different kinds of readability.

Still, I appreciate Ruby pushes on the linguistics. It’s different. It’s challenged my opinions on what makes for good code.

That said, I’m finding that, like most things, after awhile you get accustomed to the syntactical nuances of a language. Your eye movements readjust and your brain figures out how to unravel the code differently.

--

--

On Building Software
On Building Software

Published in On Building Software

A collection of short essays on designing, building, and maintaining software for lone wolves and super-small teams.

Ka Wai Cheung
Ka Wai Cheung

Written by Ka Wai Cheung

I write about software, design, fatherhood, and nostalgia usually. Dad to a boy and a girl. Creator of donedone.com. More at kawaicheung.io.