Coding as a way to communicate
This articule is also available in Spanish here.
Este artículo lo tienes también disponible en español aquí.
Ok, you are a developer, what if I told you that your work is not only a bunch of code but a form of communication itself?
Yeah, I’m pretty sure what you are thinking right now:
“Dude, you think you discovered the wheel? I talk to my computer through my code and everyone knows that!”
And that’s for sure, the code itself it’s the way that we as developers talk with computers to tell them what we need them to do, but that’s just the tip of the iceberg!
Code is a form of communication with a computer, with other tools, with other people and with yourself (right now, in a near future AND even in a few months!).
Communicating with my computer
We rarely (or never) converse with our CPUs using their natural language (I hope no one tries to write a REST API only with machine code…), but we use this interpreters to translate our human code to machine code. This may literally be an “interpreter” for scripting languages that are interpreted at runtime like Python or JavaScript. Or we use a translator: a compiler like in Go or C++.
We talk with our computers giving them a literal list of instructions for the CPU.
Imagine that you write a list of tasks that you want to do today, for example:
- Buy groceries.
- If the new Marvel movie is out in cinemas, go watch it this evening.
- Clean your kitchen.
But what if that list of tasks is not clear enough, ambiguous or doesn’t even make any sense?
- Buy your kitchen.
- If the new groceries is out in cinemas, go watch it this evening.
- Clean the new Marvel movie.
If we want our code to do exactly what we want. It must be crystal clear and unambiguous so your instructions are carried away as you want it.
Communicating with others (including you!)
Your code is a way to communicate with other people, but not for talking about the game last night or your favorite TV series episode from last week.
Your code speaks to others who have to read what you have written. It is read by the people you work (or collaborate) with. It is read by the people who review that code. It is read by other team member that picks your code later on. It’s even read by yourself when you have to fix something in a few months.
Our code is communication with others. Even with you. It must be crystal clear and unambiguous as well if others have to maintain it.
This is pretty important!
Our code should be transparent: exposing the algorithms and revealing its intent, not making it obscure and hard to read.
It should enable others to modify it easily. If the code doesn’t reveal itself, showing clearly what it does, then it will be difficult to maintain or change.
Remember that about coding we only know that the only constant is the change itself.
Good code is not reduced to the point of unreadability. Neither is lengthy and boring and filled with comments. More comments don’t make a better code, they just make it longer and creates at least two possible problems:
- If you have to skip a line of code every two or three lines because it’s a comment, it’s harder to follow it’s intent.
- The comments may live longer that the code they explain, getting out of sync with the code.
If you need to add a comment to explain a block of code, you should think first of rewriting that block of code.
A good piece of code should be a balance between using the right features that the programming language offers us and all the context that surrounds that code. And that context includes all the people. Making a perfect block of code that anyone but you will understand will make it harder to maintain, and from time to time someone will replace it with a less advanced version but better understandable for all the team.
Also, you must consider the natural language you program in. If all your team speaks the same language, this shouldn’t be a concern, but nowadays a lot of projects are multi-country so this must be a conscious choice that involves all the team to choose a common language to use. It’s common to choose English because the programming languages standard library and most used libraries are written in English so using the same language makes a more homogeneous code.
Code is read far more often than it is written. Therefore it should be optimized for reading, not for writing.
Communicating with other tools
Our code communicates even further than with the CPU and people, to other tools that work with it.
Right now there are a lot of tools that interacts with our code: documentation generators, code linters, source control systems, bug tracking software, code analyzers, etc. Even our code editors or IDEs interact with it.
It’s common to add extra directives to our code to get along with this tools, but it’s important to know when to stop before it affects the readability of your code.
