Writing Clean And Understandable Code

This post is about all the programming languages, wheter you are writing your code in C, C++, Python, Javascript, PHP, HTML, it doesn't matter, these tips apply to all of them.

What is clean and understandable code and why is it important ?

Reading bad code usually takes more time than it did writing it.

If you are a programmer and know the syntax, the code should be easy to read and shouldn't take much time to go through. You will have to teach yourself to improve your code writing skills, meaning that you will have to practice it and inspire yourself to take time and keep the code clean, even when writing a very simple and short code.

Code is clean, when the people, who don't understand programming or know the syntax, read the code and get an idea of what is happening on certain lines and places.

Tips on how to write a clean and meaningful code

Tip: Names for variables and methods/functions

Don't be afraid of longer names, because the name is very important and it should say everything about the variable/function. When we see a name of something, we want to know what it is or does ( variable / function ).

Avoid abbreviation ( shortened names ).

Example: there is a string that holds the value of a basketball name for a short kid, we DO want to use the name "NameOfTheShortKidsBasketball" or "BasketballNameForShortKid", we DON'T use the names like "kidballname" or "nameofball" or "ball" because they don't tell us all of the information we want, we have a basketball that belongs to a kid who's short, not a random ball for a random person.

Example of good method names

Example of good variable names

Tip: Comments may be misleading

Usually comments are useful, but they may be outdated. For example if a someone creates a method and comments about its work and then later changes the method and forgets or decides not to (doesn't bother to waste precious time) update the comments, they become misleading for whoever stumbles across it in the future.

This tip does not tell you NOT to use comments, it just refers that they MAY be misleading and confusing. There can be loads of arguments on this tip.

Tip: Separate method/function for each task

Yes, for better understanding of the code, separate methods for each task is important.

Why ? Because this way it is easier to find the code part you want to edit and there aren't so many lines you need to look over to find the problem while debugging and there are no unrelated parts of the code in your sight while doing that.

Example: your code is about transferring data to server safetly, you get more than one separate functions, some of them would be like this: TransferData (main method), CheckServerAvailability, EstablishConnection, GetUserIdentification, GetData, UploadData, CloseConnection . Don't just throw them all into one big pile of code.

Just remember not to go too far with this, if you end up getting only few lines per function or just callouts to other functions, you know you've gone too far.

Tip: Separate classes if possible

You should classify if you get multiple variables and/or functions for one and the same usage or if they are refering to one and the same item that you could convert into a separate class.

Example:

You have the variables: Name, Sum, ...

And you got the functions: SayHello(), GiveMoney(), AskForHelp() ...

This tip applies even if you have two variables/functions for one item/case/use.

Tip: Don't repeat yourself

This saves a lot of time, code space and nerve. Try to make it so that you do not write things over and over again, if you know you need to use the same thing in multiple places, just make a new class and make instances of it later.

This also applies to cases where you need a similar code block to earlier work, and you can just copy it from where you used it before and edit it accordingly.

Example: you are going to have tables for separate tabs, just make a new class where you customize the table and add some methods for later customization when you use the class by its instances.

Tip: Handle the exceptions

Try to see where you might get an error during the code launch and use. This eliminates possible future headace and extra work and also makes your software more user friendly by not crashing or doing something unexpected.

Tip: As few arguments for functions as possible

More arguments means harder debugging and reading for the editor. You would have to find where the arguments were edited/used/given and trace them all the way back to whereever.

Tip: Leave SOME whitespace

Whitespace should be between separate sections of code: loops, functions, variables, tasks, etc. It gives the eye some rest.

Important is not to have too much white space, as the code gets too long and makes it harder to see the overview or even find what you need.

Why do we get impure/dirty code ?

Mainly the lack of time and the fact that people are impatient. People usually want to get things done quick and tend to make mistakes. If you don't take time to write a code that you'll easily understand, the code will be difficult for you to read later on.