4 psychology challenges of code readability
Or: how the programmers’ emotions may affect the pace of development and the quality of a codebase
I have been writing in this space lately a lot about the Front-end development stack. However, my favourite topic of conversation every day when among my peers is code readability, a subject obviously not exclusive to Front-end and, mind-bogglingly, often put aside as unimportant.
One reason for this is because its impact cannot be measured in the same way as, let’s say, either whether a product works at all or its performance, which are both things fairly easy to measure. There are many other reasons though.
Obviously, the primary concern of a developer is to make something that fulfils its requirements and a very close secondary concern would be to have something that performs well doing so. However, if we don’t pay any attention to the maintainability of the codebase, particularly readability, we may fall into an ever-increasing difficulty to write new code that works and performs well, to a point where all code has to be thrown away and everything has to be redone from scratch.
Sounds like an exaggeration? Well, listen to one of the many stories from lecturers like Robert C. Martin (a.k.a. Uncle Bob) about companies that didn’t even have the opportunity to rewrite their codebase, going down before that because of code quality issues and the consequent delay in developing their promised products.
Making code work and perform well is all about dealing with computers. Code readability, on the other hand, has everything to do with humans and their psychology, which is a challenge to most programmers, that deal much better with unsentient machines.
After literally decades of observation since the 1990s, I identified some challenges where the personality of programmers had a tangible impact on endless codebases out there.
Challenge #1: speed
It is said by some of the best minds out there (Cooper, Fowler, Martin) that good development is not equal to fast development, sometimes the opposite being true. Being “slow” in this case means making sure the project doesn't end like so many out there that start lightning-fast, with the initial phase of development not carefully thought as it could have been because it was too rushed, ending up very sluggish on its development because it gets too hard to traverse eventually.
In other words, good development in this view would be to have a development speed that is as constant as possible, even if it is not as fast as possible sometimes. Walking at baby steps initially, with enough care that ensures the future developers will be able to figure out the code even if it expands vastly.
The problem with that is that programmers usually like to go fast, especially at the beginning of a project where they have this so-called “greenfield” situation, basically a blank canvas open for their brush strokes. Even with an existing codebase though, developers like to be productive, eager to take a peek at what awaits in the next corner, to have a different challenge every day and not to spend too much time on a single task, especially one that may have been already untangled.
Solution: as said at the start, to go slowly but surely.
Challenge #2: a narrow view
Readability concerns — particularly naming conventions — require the developer to always take a step down and get a broad view of a project, either to understand its concepts so they can come up with meaningful and efficient names and also to avoid name clashing.
Psychology tells us about how the different sides of the brain take up different kinds of tasks and how some people use one side more than the other. Roughly, the left side of the brain is all about focus and logic, while the right side is about broadness and abstraction. I made an image a while ago for a presentation about code naming:
It is clear that the everyday routines of a programmer’s job focus almost exclusively on the left side of the brain, which is intended and harmless in itself. The problem is, we need a bit of the right side for naming, as good naming requires broad thinking.
Stepping out of a codebase to switch out of the focus bubble and have this “bird’s eye” view is in practice fairly cumbersome, especially if the programmer is all day surrounded by intricate logical challenges, which is often the norm.
Solution: some can be proposed for that, like to have temporary names to be used in practical coding until the end of the coding section, where the definitive naming is established; or discussing naming with the team before starting to code. Regardless of what is decided, the simple act of acknowledging the issue is sometimes enough to at least put the important issue of naming on a better focus, which may become relevant for the quality of a codebase.
Challenge #3: unpredictability
Robert C. Martin a.k.a. Uncle Bob, in his book “Clean Code”, has a nice quote:
You know you are working on clean code when each routine you read turns out to be pretty much what you expected
Needless to say, I agree with this. However, not all developers seem to agree with this and people often refuse to praise code that sounds familiar or predictable. They expect their “good” code to have mystical structures, unreadable one-liners, things that tell the world the writers are more than simple and boring humans… they are almost machines themselves.
There are a number of problems with this. To start, developers are humans, and whether they are fine with this or not should only be their problem, not extended to anyone else. It often is extended to other people, unfortunately, because the “mystical one-liners” often are encoded bombs set to explode on someone else’s lap.
Curiously, the unfortunate human that will take the burden of deciphering a code that was not made to be read by humans often praises the code that is their own trap, which is profoundly telling. They fail to see that they are taking many times as long to maintain some code because some other dev wanted to flex their “brain muscles” needlessly.
This “flexing” is the central issue here: developers write mystical code because they want to be praised, they want to be recognised as artists of their own craft. To me this reveals two major issues:
- they ignore that programming is not an art, it is a form of communication that has to be clear. Programmers are always being paid not to express themselves in beautiful ways but to write code that is maintainable, serving not only machines but also other people;
- by judging predictable structures as “boring” and the ones who write them intellectually less capable, they try to impose overly complex code at a high cost for their employer. This is very selfish and indicative of a personal issue of insecurity, for which companies and other people shouldn’t be punished.
Bottom line: code is meant to be read. It is always read way more times than it is written. Readable structures may look lengthier or even seem less noble because they are deemed “too simple”. One question though: if code didn’t have to be readable then why there are high-level languages at all?
Solution: to be professional, which means to undress oneself of vanity and be respectful towards other developers (including oneself in the future) that are going to read some codebase and try to understand it.
Challenge #4: trends
To be a programmer, regardless of which purpose or which language one uses, implies being always updated on what’s going on. New technologies come and go all the time and, with them, people often see themselves dealing with deprecations and security flaws that need to be addressed and better technologies to be used to improve their career lives.
However, having to be aware of what’s going on and exposed to daily changes on the very foundations of one’s work sometimes brings the risk of going overboard on the latest trends and losing focus on what is important. This happens not only because the subject may offer its own possibilities, but also because it allows one to belong to a group around that trend.
Being a JavaScript developer I obviously am aware of the “one new framework a day” thing, which can become exaggerated very quickly and is already impacting the Front-end scene, making it somewhat tiresome (although I should say, please ditch JQuery, we are in 2021).
Regardless, this is not a Front-end exclusivity: lately, there has been a lot of talks about companies replacing their programming languages of choice on the Back-end in favour of trending alternatives. This is fine if there is a need or a clear benefit, but we know that sometimes this is not the case and people just want to have the new shiny thing.
Even programming paradigms can be more of a trend than a need. When Java was all the rage mid-1990s people switched massively to object orientation and made classes even without any need for them, impressed by the examples at the time showing that a new class Customer would extend a class Person and inherit from it. Those examples were often useless and added no real benefit to projects, but they massively shaped the way people thought back then.
Now we are just starting to question another trend, very popular now although not that new, the functional programming one. Just like object orientation, this paradigm is not necessarily good or bad, but people sometimes get really religious and polarised about it, which is obviously helped by our social media channels that instigate disagreements and prioritise dividing opinions.
Other things like microservices, microfrontends, monorepos, certain aspects of particular stacks, languages or even certain standards pushed as the next panaceas always have to follow the rule of utility, which is pretty obvious but sometimes overlooked: they should be used to serve a purpose. If they are become a purpose by themselves, that’s a bad sign.
Finally, I have been seeing articles lately that benefit from dividing algorithms that sound funny to me but, judging by how much attention they seem to get, they can be a real danger. Things like “stop using X” are concerning to me, especially for junior developers and also especially if those things are simple readable structures like if or language features like logs.
Solution: to be sceptical about the benefits of changing any stack without urgent need. Also, about articles claiming the next panacea, everyone’s social media filters should be very well calibrated at this point, so let’s use them.
Conclusion
Programming is a human matter. As mechanical and logic-oriented as the mind of the programmers is, they are humans after all, subject to emotions and, because of those, willing to make mistakes, sometimes even intentionally. Coding too fast just to get to the next challenge asap, resorting to bad naming because having a broader view feels uncanny, making code too complex only to gain questionable fame and embarking on trends to feel like belonging to a group are only some of the possibilities.
In the end, developers shouldn’t feel like they are bigger than the problems they are trying to solve and, above all, they should take into account the limitations they inherit as human beings and take care of their mental health and emotional state just like any other person.
