Few programming tips and principles to write readable code

Writing code for a Software is often challenging, especially when we’re building a large software, and different people has access to the source code, and each one is allowed to write their piece of code. Throughout these past years, I’ve worked on different software projects with different teams, and I must say not all code I’ve written I could even understand but it merely just worked. "I often wonder how". Stats have proven that software developers (coders) spend more time reading than actually writing code. Before I starting writing any piece of code, these are the steps I follow:

• Understand the problem:

The mistake we usually make as developers, is to start our processes without understanding what we are trying to solve. Understanding what the problem is, is always the first step (we all learned this when we first started); this simply entails that we should first understand the problem to be able to come up with possible solutions for it.

• Define at least two possible ways to solve the problem:

Having different ways to solve the problem, helps the developer or the team to select the most efficient way or course to follow to achieve the solution. Eg. Let’s take a real-life example, when we use a modern GPS it simply gives us at two different routes or more to select so that we choose the one with less amount of time or the one we feel more comfortable with.

• Select the best solution amongst various possibilities:

After understanding the problem and defining the different ways to solve the problem, you have to select the most efficient way to achieve the optimal solution.

• Document:

Most of us neglect the documentation. The documentation can be used as a reference to solve similar problems in future, and help future members of the team to understand the how the problem was solved.

• Pick the best programming language to solve the problem:

Now that we have a good understanding of the problem and everything is documented, we need to select a programming language that will help us to meet the desired solution. When choosing the programming languages, you will need to have a list of potentials that will help to reproduce the solution you’ve selected.

Developing the solution

After selecting the best programming language to solve the problem, you still have to define some other things to better your coding environment and write readable code, so that anyone can easily understand our code and maintain it in future. I would like to share a few rules I normally follow to keep my code clean and maintainable:

• Folders and files organization:

As beginners we tend to write our code in a single file, for an entire solution (“I have done it a lot”), but as the solution for our software expands we’ll end up with a lengthy page, and we may get lost in our code, which will be a nightmare to maintain. The solution is to separate your code using folders and files containing specific parts of your software.

Desired file and folder structure (Node.js example)

• Select a naming scheme to use throughout the project:

This takes me back to a common mistake most of us made when starting. Having a scheme for naming your variables or functions literally helps to define a clean and consistent style. I often use camelCasing (where the first letter of each word is capitalised, except for the first one) as a scheme for naming my variable, functions, and classes.

string myString //variable 
myFunction() //function 
MyClassName //class 

Note that for classes; it is preferable to start the casing using a capital letter.

• Use names easy to remember for your variables:

A well-named variable helps the developer of the code or the others on the team to easily understand when to use this variable and why it is there. Let’s say we want to sum two numbers then we would use the following names for our variables; sum, num1 and num2.

int num1; //receives the first number
int num2; //receives the second number
int sum; //will store the result of the sum of both numbers

When naming our variable or even a function, or class you must have in the back of your mind that the name you are selecting must define the action we desire it do. “A long descriptive name is better than a short enigmatic name. A long descriptive name is better than a long descriptive comment.” - Uncle Bob

• Comment your code:

most of us ignore comments thinking that we since we wrote the code we know what’s happening; which is wrong. The comments won’t only help you but they also help your team to maintain the code. Comments always help since they are a small explanation of what a specific block of code does. Although using comments is helpful, we should also avoid commenting obvious blocks of code so that whoever is reading don’t have to spend time reading something that is clear to understand.

• DRY principle:

DRY stands for don’t repeat yourself; this principle states that; “every piece of knowledge must have a single, unambiguous, authoritative representation within a system”. Basically you have to avoid coding the same thing more than once, by sharing the common code by using functions.

https://www.youtube.com/watch?v=Mw0AdBg4c8M

Once again not indenting code is a mistake that I’ve seen lots of beginners and even people with some experience making. Indentation helps a lot in the readability of your code, it helps to understand where a block of code started and where it finished for example. I can say that if you indent your code in a consistent manner you will end up having a beautiful structure which will be easy to read and understand.

Wrong

Well, there other principals that we as developers can use to improve our way of coding, these ones that I shared here are just a few of them.

Right

As Uncle Bob says “Clean code is not written by following a set of rules. You don’t become a software craftsman by learning a list of heuristics. Professionalism and craftsmanship come from values that drive disciplines”.

“Draw twice code once”