It's all Greek to me: Thoughts on code readability and aesthetics

Shakespeare in his play Julius_Caesar wrote:

CASSIUS: Did Cicero say anything?

CASCA: Ay, he spoke Greek.

CASSIUS: To what effect?

CASCA: Nay, an I tell you that, I’ll ne’er look you i’ th’ face again. But those that understood him smiled at one another and shook their heads. But, for mine own part, it was Greek to me.

For Casca what Cicero said, was not clear, as he was not speaking Greek, but if Cassius had heard what exactly Cicero said in the first place, he would (probably) be able to understand, since he spend big part of his life at Rhodes where he studied philosophy and became fluent in Greek.

In Greece, we have a similar phrase to express something confusing, "Μου ακούγονται κινέζικα" (“They sound like Chinese to me”), while in China when they want to express that something is confusing they say that its written in the language of the ghosts, or it came from the sky.

In Germany, they say "Das sind böhmische Dörfer für mich" (“These are Bohemian villages for me”), which has an interesting origin. In 16th century, in the Habsburgermonarchy the main languages were German and Czech (known as “böhmisch”), so the travellers simply did not understand the names of some places that they were visiting which had Czech names.

The problem with these phrases is that while they sound funny, they hide a sort of stereotype underneath. Certainly, there are languages that are more difficult than others, but most of the times is a matter of familiarity and not a matter of ability.

The same thing applies to programming languages. Yes, php has problems, javascript’s prototypal inheritance makes many OO devs hate it and Java has its own issues, but let me, tell you a secret:

There is not a single perfect programming language. - Avraam

And yes Rails devs, I mean it, Ruby is not perfect either.

All of us have seen comments like “You wrote this like a Javascript developer”, attacking both the language and the writer. You know what? It’s not the writer, neither the language. It’s our familiarity with it.

“Can you write it like that… is more readable”

Do you remember the first time you wrote something in a new programming language and you run it, and it worked? Didn’t you had this “OwO, I am a Perl developer now, let’s put it on the CV” feeling? Until, someone else come to you and say, “No, no, no, you can squeeze these 10 lines, into this one-liner”… And this one-liner its most of the times a cryptic monster.

It’s not because you are dumb, and the other person is smart, its because they are more familiar with the idiomatic way of doing something in that specific language.

Idiomatic: Using, containing, or denoting expressions that are natural to a native speaker.

To understand better, let’s see some examples.

You can write this in Ruby

a = []
for x in ['a','b','c'] do
  a.append(x.upcase)
end

But the idiomatic way, its probably:

['a','b','c'].map(&:upcase)

In Javascript each array has a .length property that holds its size. The idiomatic way to check if an array is empty is:

if ( !array.length ) ...

Of-course someone could write

if (array.length === 0) ...

But that is not the idiomatic way!

For a C developer, either way is probably weird, since arrays in C have a fixed size. So, it’s not only how we express our intentions (idiomatic or not), its also the meaning behind our expressions. For a javascript developer an empty array is an array without elements, for a C developer an empty array is probably an array where all the elements are NULL.

So, if idiomaticity plays such a big role on understanding a piece of code, what exactly means “readable” code?

It’s not what you are able, its what you are familiar

Anyone who has visit Japan knows that Japanese people are very polite, there is “Arigato” (thank you) after every second sentence. If I start saying “Danke” in Berlin, as often as Japanese say “Arigato”, everyone will start thinking that I am a weirdo, not polite.

Each culture, and micro-culture has its own customs and manners, and programming languages (frameworks/tools as well) form micro-cultures, the more time you spend inside a specific community of thought, the more you are shaped by the way the people of that community are thinking. As Winston Churchill once said, We shape our tools and then the tools shape us.

The problem is that the more fluent we become in a specific language/way of expression, the less plasticity and flexibility we have to adapt a new unfamiliar construction. We see the world through a very specific perspective.

Read-ability

Many times when we are talking about clean/readable code, we are not talking about complexity, but unfortunately we are talking about aesthetics.

There are developers who will declare variables like:

const shortDescription = "blah blah";
const descriptionLong = "Blah blah blah";

Some others will find it unbearable that the = signs are not aligned, they will go and open a PR to change it to:

const shortDescription = "blah blah";
const descriptionLong  = "Blah blah blah";

Is this a matter of readability, or a matter of aesthetics? Is this the biggest problem of this piece of code? I would argue that the biggest problem is not that the = signs are not aligned. The biggest problem is (probably) that one of them starts with adjective, while the other one with a noun. I would say that more valuable pull request would be to change it to:

const shortDescription = "blah blah"
const longDescription = "Blah blah blah"

The real question though, when we are talking about readability, is:

Who is reading ?

If you ask 10 developers on what is readable code, or how to make a certain piece of code more readable, you will probably get 10 different answers, depending on the level of fluency each of them has with the language.

I want to give a definition on what is readable code for me:

Readable code, is a piece of code which can be understood by the most inexperienced developer in the team, in a reasonable amount of time.

Each language has its own idiomatic way of expressing something, and each of us has their own aesthetics, but at the end of the day, we want to be understood, or at least we should want to be understood.

I am tired of people that are trying to write the shortest possible on-liner to blow their own trumpet on how smart they are (I am looking at you Perl), only to discover a few days later, that they, themselves, are not able to understand what they wrote.

There is no space for Poetry in production systems (specially if you are trying to write Haiku).

My code fails.
I do not know why.
My code works.
I do not know why.
Ian Johnson

Summary

• Next time we have a conflict with a colleague on what is “readable”, let’s ask ourselves “Am I talking about understandability or I am talking about aesthetics?”
• Let’s show some empathy to the people who are not familiar with the idiomatic way of expressing something in our language.
• Every language has defects. Every.
• Let’s not try to be smart. Let’s try to be understood.

The limits of my language are the limits of my world. -Ludwig Wittgenstein