If you are an enthusiastic programmer, there probably have been numerous times when you have written a piece of code and, after a few days, you looked back at it and wondered, “What does this thing here actually do?”
So why does this confusion happen repeatedly?
For a host of reasons including the likes of:
Poor and illegible variable choice.
No variable declaration.
No comment lines.
No indentation.
No aesthetics.
Inconsistent spacing.
It is for those exact reasons I have come up with this article where I am going to explain the different ways of writing a beautiful and super-legible code. So what are we still waiting for? Let’s begin without any further ado.
1. Use meaningful names for your variables
Using meaningful names can help you keep a proper track of the variables used in the program. This can save you a whole lot of time and inconvenience when you look up the code at any later time for any debugging purposes.
Here’s an example for your reference:
Say, the given program is based on simple addition where two inputs have to be taken from the user, and the resulting sum has to be shown on the screen itself.
User input:
a = 10 (assumed just for the sake of our explanation)
b= 13 (assumed again for the sake of our explanation)
Now, you will have to find out the sum, and you did this:
c = a + b
So do you think the variable “c” works out well there? Technically, there’s no problem with the code, but as far as its readability’s concerned, the variable “c” raises a question mark.
Possible solution: Using a meaningful variable that an outsider can understand in a jiffy. How about using just “sum”?
sum = a + b
It works; right?
2. Use comment lines to improve your code legibility
“What is this doing here?”
You would have easily known the answer if you had written explanatory comments to go along with the code at the start.
So if you really want to write a super-eligible code that explains itself automatically to an outsider (one, having no prior idea of the matter), commenting is an absolute must for you. Here’s a simple example for your reference:
def somefuction (x, y):
#summation of x and y (comment line 1)
sum = x + y
#returning the summation of x and y (comment line 2)
return sum
Note: The comment lines are written with a # and are mentioned in bold in the above code snippet.
3. Avoid arbitrary error messages; provide meaningful ones that direct to a solution
A user-friendly error message can play a vital role in determining the source of error, and that too within a short span of time. Your endeavor, as a software developer, should be to come up with one such that even a non-technical person can understand the problem in a jiffy.
Say, for example, a program wants the user to provide any input greater than 10. The message displayed is:
Please enter any number GREATER THAN 10: [cursor blinking]
The user enters 7 and quickly presses on the “Enter.”
An on-screen error message comes up showing something like:
ERROR! Your input is NOT greater than 10. Please double check and try again.
Now, that is what I call a proper error message. The user can understand his/her error in a jiffy (no matter whether s/he’s technical or not) and can take immediate measures to rectify the same.
So NEVER come up with arbitrary error messages like:
ERROR! TRY AGAIN.
Try to come up with meaningful ones that link to a solution.
4. Be consistent with your indentation
Maintaining consistency in code indentation can help a lot in improving its legibility.
Here, take a quick peek at these two snippets:
STYLE A
function campaign () {
if ($maybe) {
do_it_now();
again();
}
else
{
abort_mission();
}
finalize();
}
STYLE B
function campaign () {
if ($maybe) {
do_it_now();
again();
} else {
abort_mission();
} finalize();
}
Both style A and B are technically correct, but if you take a closer look, you will find that B is maintaining a more consistent level of indentation in comparison to A.
Thus, as far as code readability is concerned, B triumphs over A, and that too by a fair margin.
So that concludes the article for now. Hope you had a good and enlightening read.