What does code readability mean?

This is one of the things that get all weird the more I think about it.

Trying to define an objective term like "simple" is of no use if you can't map it to something in human perception. Let's say we have some all-knowing oracle that can tell us which algorithm for problem X is the simplest one. If nobody would agree, what is the point? Or, if 51% of programmers would say A is simplest while the other 49% consider algorithm B more simple, should we just go "yay majority" and call it a day? In reality we have no way of knowing which one is objectively most simple, because at least regarding this domain, we as humans are unable to make an objective judgment.

Is the simplest solution always the one with the least lines of code? Least number of classes? Singletons vs static classes? Recursive approach vs. iterative approach? C style linked lists (next-pointer in data type) vs. "proper" list class? In general: Could we formalize this, ie. come up with an algorithm how to determine how simple code is?

Often times code that is easier to understand might be harder to work with, while more elaborated code with indirections and abstractions is harder to grasp (simply because it's more LoC/classes, just more reading), but once you got familiar with the code base, much easier to work with. So when you say objectively simple, do you mean "simple to understand so you can tell what it does", or "simple to understand wrt maintaining, extending and fixing"? And which kind of simple should I go for when writing code?

The article hints at it, but your sense of the readability of a codebase changes the longer you are exposed to it. Patterns that make it easier to become moderately competent in a particular codebase can actually make it harder to become expert. So if you want to maximize readability, you need to estimate how long future maintainers will live with your code.

Will they drop in and do a single commit and never look at it again? Then make sure everything you need to understand a piece of code is right there next to it.

Will they work on it for a long time, changing many parts? Then be very consistent with the patterns and idioms you use across the project, so that their previous experience changing other parts of it helps them understand how to make the next change.

In your first example, both are exceptional, so really "which is better" is irrelevant.

In the second, the difference is so big that it's obvious for anyone which is better, but that still doesn't make it useful for getting better at painting. "Paint more like a Van Gogh and less like a kindergarten kid" is not useful advice.

People do have art critics and manuals that attempt to write down exactly what made Van Gogh paintings great. Those writings are useful, and many artists do indeed study them.

I still see symmetry:

That the computer cannot receive joy from code does not mean that I can't; That the computer doesn't experience joy from Macbeth doesn't mean that I don't.

Reading joyful code is a treat. I pity who has not read some code that has brought them joy. And yet, what brings me joy[1], [2] is what the peanut gallery may call unreadable. What then?

[1]: www.nsl.com/papers/origins.htm

[2]: cr.yp.to/qmail.html

Surely something else must be going on.

Kernighan and Plauger, while otherwise dated, has one of the best rules for programmers:

Say what you mean, simply and directly.

Assume the best of the writer of the code you are reading; assume this was them saying what they meant, as simply and directly as they could.

Was it clear in their mind?

Or does it feel like they were muddling through the problem?

If as I am decoding this foreign thing of other people's code, I find my mind repeatedly would put it simpler, cleaner, and clearer, I can complain about the tedium, and mindless repetition in the code, but I'm still not complaining about it's readability.

Good writing is not necessarily readable writing. Shakespearean works are good writing, but they are most certainly not easily readable. There is code that is great code because for many other reasons than readability.(Like performance, correctness, robustness)

Easy to read writing is simple and concrete. Code that is easy to understand is also simple and concrete.

Complexity and abstraction push away understanding like two positive magnets. But sometimes readability is worth sacrificing to achieve a separate goal with the code.