If you’ve only started learning programming, you have to spend a substantial amount of time improving your knowledge and skills before you’re able to write quality code on the level of an experienced programmer.
But there is one thing in programming which you can do as easily as any senior software developer. You can make your code tidy and professionally looking even if it’s the first day of your programming education.
The word “tidy” in this case has nothing to do with code efficiency or other complex programming topics. It’s simply about visual tidiness and good manners.
Always format your code properly
Write tidy code from the very beginning, starting with the first several lines of code you type after watching some video tutorial or reading a programming book.
“Tidy code” means that it has proper indentations, clear self-explanatory names for variables and functions instead of “a’s” and “b’s”, and its logic is briefly explained in comments at the top of each potentially confusing logical block.
This is the matter of habit, it doesn’t require any complex knowledge or experience. You just have to apply a set of rules of writing and formatting code which is established for the language you chose.
If you don’t do this from the beginning of learning this language, it will be difficult to change a bad habit later, so try avoiding this mistake.
In order to see why this is so important, compare the following two pieces of code. Don’t worry if you don’t fully understand what’s going on there. Just focus on how it looks and how it feels when you read the code.
Function #1:
// save a new blog post into the database
function saveBlogPost(title, body) {
let blogPost = { title, body };
BlogPosts.insert(blogPost);
}
Function #2:
function abc(a,b) {
let p = {title:a,body:b};
BlogPosts.insert(p);
}
These two functions do exactly the same thing — they both save a new blog post into a database. To do this they get the blog post title and the blog post body, “pack” them into a special blog post object and insert that object into the database.
Both functions work correctly, none of them is worse or better from the point of view of logic or efficiency. For the user of this code the final result will be identical regardless of which function was used.
Why the first code example looks good
The first function is self-explanatory: when you read its code, you’ll likely understand what it does even if you have zero prior experience in programming.
This function has clear names for itself (saveBlogPost) and its parameters (title, body). It is also introduced by a brief comment written in plain English, providing additional context about where exactly the blog post will be saved.
Also, the first function is formatted neatly. There are spaces between the names of function parameters. Both logical parts of its body are separated by a blank line, so that you instantly understand when the first step ends and the next one begins.
Note that inside the curly braces all the code is indented to the right, which means that it’s nested into the function. Such indentation helps instantly grasping hierarchy of the code, i.e. what is the part of what.
In some languages, like JavaScript or C, such indents are purely decorative and only help reading the code, while in the others, like Python, writing this way is a language requirement — otherwise the code won’t work as expected.
Why the second code example looks bad
The second function is the opposite of the first one in terms of its look — it’s really “ugly”. It has a meaningless name “abc” which tells nothing about what this function does, and there are even no comments to explain this.
Its parameters are “faceless” too (“a” and “b”), so the only way to understand this function is to read its body, which is placed between the curly braces. Let’s explore it line by line.
The first line of the function body gives us a little hint: this function works with something that has a title and a body. But it is still unclear what exactly is going on there.
Only the last line of the function body sheds some light on a purpose of this code: it inserts something with a title and a body into something called BlogPosts. Chances are, it’s a database, but it might be not, who knows. By the way, we’re lucky that this database (presumably) at least has a meaningful name “BlogPosts”, since it also could look like “BP” or, say, “_b1”.
This function is also formatted badly. There are almost no spaces between the elements, no horizontal indents, no blank lines between the logical parts. Because of all of this it’s quite uncomfortable to read.
Isn’t the shorter code always better?
Nevertheless, one might say that the second function is actually better than the first one, since it’s shorter, so you spend less time writing your code this way. At the first glance it might seem reasonable, but actually it’s not.
The process of inputting characters from your keyboard will take a small amount of time you’ll spend on programming compared to the time spent on figuring out what exactly you should write. It’s typical for a programmer to spend several hours just thinking (or thinking and reading documentation), and only several minutes writing the solution down.
So, saving two, five, or even a hundred characters is not a worthwhile optimization of your programming process. Especially if as a result you get such a bad-looking code which is hard or even completely impossible to understand. Even you yourself will struggle reading this code some time later.
During the programming learning process sometimes it will be tempting to neglect this tidiness and start writing sloppy code with all of those “a’s” and “b’s” as names for variables. But you should never do that because it will insensibly harm your coding habits.
In the real-life projects you’ll be working with real-life objects like “users”, “documents”, “blog posts”, etc. If such an object in your code has a name “a” instead of “user”, and your code has a length of 500 lines instead of 5 or 10, it will be a nightmare to write this code, not to mention reading or modifying it afterwards.
Three simple rules of writing tidy and professionally looking code
So, to make your code looking tidy and professional, always do the following:
1. Write short comments, describing the main logic and the purpose of your code. But don’t comment every single line of your code, like variable declarations, etc. Focus on the most important logical blocks and branches of the code. The more experienced programmer you will become, the more self-explanatory and not requiring comments your code will get.
2. Give your functions, variables, and other objects expressive names.
3. Follow the style guidelines for your programming language. You can always find them on the Internet, simply googling with keywords like “JavaScript style guide”.