When writing code, let’s write for others!

As a computer science student, it is more often to be writing code just for myself and sometimes for my teaches, but this last case is peculiar because they don’t usually read the code (or quit it while trying to do it). There is a joke between programmers that generally not even the one who wrote it would understand its code after some time.

But the reality is that a software engineer doesn’t write code just for himself; it writes code for the whole team, and if the project is open-source the code is written for the entire world (yeah, the everyone is judging if you used white spaces instead of tabs).

And all this brings us to understand that “Clear is better than clever.” I have thought about it lots of times (I will write about some of these times bellow), but right now, this idea came because, in one of my classes, I was asked to write about this topic using as reference this article by Dave Cheney.

The complexity-experience relationship

When we are learning to write code usually start writing really messy code, it has no real structure nor order. As we learn more, our practices start to get better (I know I’m pointing the obvious) we follow the instructions pointed to us by our superiors (teachers o even managers). But then, we start to learn some fancy coding syntax of the languages like:

main(_){_^448&&main(-~_);putchar(--_%64?32|-~7[__TIME__-_/8%8][">'txiZ^(~z?"-48]>>";;;====~$::199"[_*2&8|_/64]/(_&2?1:8)%8&1:10);}

And then we return to that kind of code we did a few weeks back and don’t understand anything about it, and that’s when we finally understand the importance of making the code for humans not for the computer not to make it fancy and please never do it for the “lols.”

But the reality is that a software engineer doesn’t write code just for himself it writes code for the whole team, and if the project is open source the code is written for the whole world.

I created this chart just to represent this, in the end, there are going to be sometimes your code is going to be complicated, don’t get stressed about it but when you know how to make something simple rather than complex do it that way!

A bit of my experience

Last summer, when I was a Facebook, we used a version of Mercurial for version tracking, and everyone worked on their branches before merging them to the master one. But for merging, we were required for someone to approve the changes we were doing, and I experience some times that my changes were rejected because they were not clear enough. As I understood better how everything, how the codebase worked as well as how to get info from the internal resources I appreciated this principle and internally hated those pieces of code (or documentation) that were not clear enough because someone was lax while reviewing the change!

As an anecdote, a lot of times happened that my teammates didn’t want to review my code because it wasn’t clear, but the problem wasn’t precisely with my code, but with all the math I needed (I was working with geometry) so they didn’t understand it. To solve this, I started explaining in-code comments about what the math did and the creation of some documentation. Sometimes it’s impossible to make it clearer, but there are other ways to try to break this gap!

I’ve talked about complexity and clarity but what about readibility

I know readibility is a concept a lot use for this conversations but something readable is something that can be subjective:

“Readability is nit picking about line length and variable names. Readability is holy wars about brace position. Readability is the hand to hand combat of style guides and code review guidelines that regulate the use of whitespace.”

Dave Cheney

I know this style rules that can make the code readable or not are importante (more with naming conventions rather than tabs vs spaces), but at the end of the day there is an importance to be capable to understand a code by its structures and comprehend what it is supposed to do just by looking at its returns, not by reading every single word in there.

We could be using one letter variables and create this simple function:

int a(int b, int c) {
	if(b > c) 
		return 1;
	else if (c > b)
		return -1
	return 0;
}

Just looking at the structure you understand that it receives two integers and returns an integer, and inside the function it returns 1 if the first one is bigger, -1 is the second is bigger and 0 if they are equal. Simple enough and you didn’t need to understand why y decided to use those naming variables or tabs instead of white spaces.

I’m not saying to not respect some conventions, please respect them (please don’t use one letter variables), because in larger pieces of code maybe you don’t read every word but you try to understand every two or three lines!

Let’s only agree with something

When coding before introducing something fancy, just remember these three principles:

• Simple is better than complex
• Clear is better than readable
• Don’t make the last one a excuse to write lazy code!

Initially I was going to write just two principles, but the third one is as important as the other two 🙂

Happy coding!