Any fool can write code that a computer can understand. Good programmers write code that humans can understand.
Martin Fowler
Imagine this picture: you are going to work on a Friday morning. You had a great night of sleep. You want to get there early so you can have some peaceful time to test your new ideas on the code you’re working on.
In front of you there’s someone driving a beautiful Mercedes. There’s a highway exit in 300 metres. Your exit. Both the Mercedes and you are driving on the right lane. So you use your right turn signal.
When you get to the exit, you smoothly start to turn your wheel to the right. But wait: suddenly, the Mercedes is doing the same movement: he’s taking the same exit although his right turn signal isn’t blinking.
The Mercedes looks new, so it’s not probable that his turn signal is broken. But, you think, ‘man, it’s Friday, it’s early in the morning, perhaps he simply forgot…’
So now he’s still in front of you, and now you both reach a roundabout. There are three different ways out of it. Yours is the second. So after leaving behind the first, you use your dear right turn signal.
The Mercedes is still in front of you, and it seems to be going to take the third one. Or so you think, as his right blinker is off.
But, guess what: he takes the second exit!
Imagine the rest of the story… it probably ends with an ‘accident’. You get its moral.
The ‘humaniler’
Extrapolating this moral to programming: REVEAL YOUR INTENT while coding. It’s not enough to pass the compiler’s checks.
I wish there existed something as a human compiler or humaniler. Something that checked the intent of our code after passing the language compiler checks; something that wouldn’t let us compile our code if it weren’t clear enough: otherwise we would be forced to rewrite it again until the human compiler ‘understood’ it and gave its OK.
Of course this is just a wish, as I wish everyone used his blinkers to make clear his intentions while driving.
And it’s just a wish because it’s not easy to compute an algorithm for human clarity in code. And that’s because a different copy of the same version of a compiler installed in a different machine does exactly the same checks, that follow the same computable rules.
But we can’t say that about human copies, right? After all, we’re not copies, are we?
The most we can aspire to is to achieve an informal common denominator of clear understanding.
Say what? Cheeze… what a terrible sentence that last one! Let me apply to myself the same remedy I’m preaching: at the end of the day, all we have is ourselves to try to make our code understandable.
Use your blinkers
After all, not all turn signals look the same, right? They don’t even display the same amount of light. But to express their intent, it’s not enough that they work properly: you have to use them.
So use your blinkers in your code! Make your code expressive, not only for the computer to understand it, but for the average human that is going to read your code in the future (including yourself).
Expressive is also pragmatic
Enough preaching. Let’s put an example.
I’m going to use some code taken from Uncle Bob’s book Clean Code (Use intention-Revealing Names, from Chapter 2). It’s a Java method, written in two versions; both versions do exactly the same thing. Take a look and tell me: how long does it take to understand each?
public List<int[]> getThem(){
List<int[]> list1 = new ArrayList<int[]>();
for (int[] x : theList)
if(x[0] == 4)
list1.add(x);
return list1;
}
public List<int[]> getFlaggedCells(){
List<int[]> flaggedCells = new ArrayList<int[]>();
for (int[] cell : gameBoard)
if(cell[STATUS_VALUE] == FLAGGED)
flaggedCells.add(cell);
return flaggedCells;
}How long did it take you? As you can see, just coding for the computer isn’t pragmatic: writing expressive code that works is.
A man must have a code. -Bunk (a character from the show The Wire)
Writing expressive code that works is also good for your reputation. Reading your code will be like entering a house that smells good.
On the contrary, not worrying about being expressive and just caring for your code to work without paying attention to the human reader will damage your reputation. I’m sure you can guess which version of the above method was written by the Mercedes guy (by the way, I never understood why they give such classy cars to such unclassy people!)
