Code Readability: Defined

As software developers, we usually agree that code should be “readable”. Yet talking about what does it mean practically immediately strives discussions and misunderstandings. Let’s try to fill the gap by thinking and logic. If we look at readability of a text we will find out it is quite well defined and affected by a few known factors:

• Optical conditions: contrast, font size affect our brain’s ability to recognize a form as a known character
• Particular font: affects our ability to identify a character (things like a Serif font is more readable on a physical medium and Sans Serif family is more readable on a [more coarse grained] electronic screen)
• Spacing/Punctuation: affects our ability to distinguish structures the text composed of: to tell letter from letter, word from word, sentence from sentence.

Note that all these factors remain below the semantic level of text (the meaning of words), they are kind of on a “mechanical” level. This leads us to understanding that readability of code should also reside at the “mechanical” layer: there are factors which either assist or hinder our brain from being able to efficiently distinguish and identify the [code] structures.

This definition gives us power to take any code readability related topic and come to a satisfying answer.

The famous curly brackets style discussion can be settled down like this:

Brackets are part of the code structure which enclosures a particular piece of code. Thus, the topmost task for our brain is to figure out which exactly part is enclosed.

Under this consideration both styles are similar: in one case the beginning is marked by the statement + bracket, in second case with only the bracket. There are opinions that bracket on a separate line is more firmly visually separated, yet the difference cannot be dramatic by our own definition of text readability: the bracket on the same line with statement is generally also separated with space.

However, there is a further twist. To understand it, we will approach another topic first: how length of a function affects code readability. Here’s one implication: if a function does not fit into a screen, it will definitely reduce readability. It is roughly similar to a word in a physical book, hyphenated to a next page: yes you can turn the page but it will slow you down, especially if you would need to re-read this a couple of times (which is a normal thing when working with code).

Now when we return to our bracket style discussion we need to face the fact that having bracket on a separate line inevitably increases line count of the functions where it is used, thus the style of curly brackets will have a significant effect on the whole code base.

And another one heavily discussed case: distinguishing separate words in names written together. There is a need of naming classes and variables with a single “word” so it naturally requires something which helps our brain to pick up the words it consists of separately. The CamelCase achieves it capitalising the first letter thus making it a visual anchor. It can also be perceived as a compressed (no spaces) version of some headers-like text thus, it does not differ much from reading a usual text.

The snake_case achieves separation differently. There is an additional glyph (“_”) which will have to be processed by our brain and processed as a character, not as a separating space, just to be “thrown away”. Thus by reading this style of separation the brain will go into a temporary mode where it would have to apply a bit more cognitive efforts to convert separating glyphs into the meaning of separator. The mode temporary because, in comparison, the vast amount of other texts we read have spaces as separators.

There are definitely other, sometimes language specific code constructions yet I claim all of them can be evaluated for readability using the approach above, to finally cease the discussions.