Recently, while reviewing some code, I came across the snippet below.
Now a keen mind can spot many issues with this.
The ones I am referring to are something specific and relevant to the business though. The code is supposed to fetch all active clients, loop through, get job specifications from some
DataSources defined for those clients, build a config object and return those values to calling function so that those jobs can be fired. Interestingly
DataSourceJobConfig definitions have nothing named as
destination_params is a property of
Client object, not of
DataSourceJobConfig. I could not make heads or tails of it. To top it, I was told the code is already working and tested, review is just a formality (like it usually is in many places).
When I started digging through the code further, I found that
getDataSourceJobConfig, was accepting list of
dsConfigs, but instead of returning a list of
jobConfigs it was enriching objects in
dsConfigs and returning the same list. Further digging revealed that the same was being done in both the methods above. Effectively, all these variables were the exact same list of exact same objects, mutated in every call, were actually the list of Clients!
This is a question I always loved when I first read Clean Code by Robert Marin (Uncle Bob). The answer takes some thought, but once you realise it, it all makes sense. We write code to tell our team members what we are trying to instruct the machine to do. The primary consumers of the code, even before the destined machine are the author and the peers who see, read, understand, refactor and maintain the code. If all one wants is for the machine to get the message, then one can talk in binary, computer languages are for people to convey to each other what they want the machines to do, along with instructing the machines.
To prove this point I have built a small snippet (and a cryptic language) and compiler. Here it is, can you guess what this code does:
Before you say it is invalid, gibberish and would just fail, let me assure you that every word in that snippet is useful, and has an appropriate meaning for what it is doing. If I were to compile this and execute it, it will work. In fact I used this snippet in a presentation to make this very point, when it worked, the output was even more confusing. Now I would be lying if I said that the compiler just compiled the java like file, it also did some transformations, like ‘afdrukken’ (Google Translate says that is dutch for ‘printing’) was being replaced with System.out.println, as if it was a function similar to python’s print.
The point I am trying to make is that instructions to a computer can be given is many ways, we use ‘Computer’ languages, with meaningful constructs and words so we understand what others are trying to instruct the computer to do.
Even before it executes, the code is read first by the writer, is read often by peers and so the goal of the code is to get the intent correctly across not only to the computers but also to other humans.
We code first for humans and then for machines.