Writing has its own rules and knowing it can help to keep your reader attention. In the programming context this is particularly important as a single detail can change everything.
That’s why in this article I will introduce you some of this codes which will help you to improve the readability of your code.
Rule 1: Always introduce the topic
When reading an text the first interaction every single user will have is the same one. They will try to see as fast as possible if the text in question has value to them.
That’s the reason why we need always to present the purpose and the value of our text at the beginning. This allow the user to see if our text interest them rapidly and take a decision according to it.
While developing, we need to have the same process in your mind. However this is done a bit differently where in a text you need to describe bit by bit to then conclude in a program you will have to slowly going down through abstraction.
To achieve that multiples methods can be used.
The first way to accomplish that is to not mix different level of abstraction inside a same function. Instead it is better to cut it into multiple ones with all a different level of abstraction. This allowing the user to get rapidly the content of a function while being able to still be details easily if needed.
Another way to do that is to organize the methods by importance so the user will first the most global and important method which will help him to know if he needs to dig down in that file in a couple of seconds.
Rule 2: Be precise
It is always annoying when a writer or a speaker refer to a notion without really defining it because you have to map by your own the notion to the definition.
That’s why a polite writer always define precisely every notion he works with so his reader doesn’t have to do the job on his own.
When you are coding this is done by naming variables, classes and functions correctly but also packages that helps developers to find classes.
To name correctly an entity in your code it needs to to follows two rules.
First the name needs to reflect the value or the class it is containing. For that is it better to use a noun to describe a variable as it is often something static and a verb to describe a function as you will be doing some actions inside it.
This will also allows you to differentiate a function from a variable in the code in seconds.
Rule 3: Keep up with your definition
Another easy way to lost your reader is to change meanings from a word thorough the text.
This will confuse the reader and force him/her to stop to read again to understand the meaning of your text inflicting him/her a increased mental effort to get it.
In programming this same error can be done by redefining same variables thorough your method or function too much. You need to remember each time you are re affecting a variable not related to the previous you are asking your reader an effort to remember the last value and type.
That’s in a strict respect from that principle that functional programming banned the re-affectation from variable prevent complex mental mapping for programmers.
Rule 4: Provide value to your reader
It is often forgotten in most paper that you are suppose as writer to bring something to your reader by changing the way they see the world.
In the case of programming the main value you can bring to your reader is understanding by changing the way they see things using abstraction.
In another words you need to add layers to your code to make it clearer and not hide numerous layers without real purpose: Your code need to respect K.I.S.S.
This point is also a point that you should keep in mind when naming your methods and your classes. Long names are often complexifying the code more than helping your readers, you should instead try to reduce the name of methods or classes to their core functionality.
If you can’t do so without using an and in the name from your method or class that could mean you need to refactor them into two pieces.
Conclusion
I hope this article helped you to understand that the job from a programmer is in fact really close to the one from a writer and that if you want to write good code then you need to make it look like a good story for your future reader.
Leave a Reply