[Gyan/ Knowledge] 10 Steps to help write a readable code

10 Steps to help write a readable code

• Commenting and documentation

IDE (integrated development environment) have come a long way and most are comfortable using these IDE’s because they save a lot of our time.

Comments should be simple and basic English understandable to everyone. Comments help us to understand the code even without going through the function. IDE’s help us by showing these comments to know what the function does while calling the function.

• Consistent Indentation

It is very important to indent your code simply because it makes it readable

Ex: in C++

Cout<<”hello world”; if(i==0) cout<<”zero”; else cout<<”not zero”;

(will work perfectly fine)

Cout<<”hello world”;

If(i==0)

{

Cout<<”zero”;

}

Else

{

Cout<<”not zero”;

}

(brackets are not compulsory, code will work if not as well)

There are many styles of indentation, you can choose any style but it is very important to be consistent with your style.

But remember when in group doing a project it is always good when all the team follows the same style.

• Avoid obvious comments

Commenting your code is fantastic however, it can be overdone or just be plain redundant. When the text is that obvious, it’s really not productive to repeat it within comments. If you must comment on that code, you can simply combine it to a single line instead.

Adding a comment at the beginning of each block of code also emphasizes the virtual separation.

• Consistent naming scheme

Function names and variables names should be consistent, readable and understandable.

It is very important to have word boundaries in names, two ways to do:

• camelCase: First letter of each word is capitalized, except the first word.
• Underscore: underscore between words, like: mysql_real_escape_string().

Similar to indent this also has many ways. It is always advisable to follow certain convention in an existing project. There is no “best” style but always remember one thing be consistent.

• DRY (don’t repeat yourself)

The purpose for most application is to automate repetitive tasks. This principle should be maintained in all code, even web applications. The same piece of code should not be repeated over and over again.

• Avoid deep nesting

Too many levels of nesting makes it harder to read and follow and sometimes even harder to remove errors (if any). For the sake of readability it is better to reduce deep nesting.

• Limit line length

As humans we are more comfortable reading small horizontal lines. So it is good practice not to write long lines.

• Use of files and folders

You can always write the entire program in a single file, but that would be a nightmare to read and follow. As the programs become huge it is advisable many files and use “include files” etc. Common files can be combined in a folder for better understanding.

• Capitalize SQL Special words

Creation of database is a important part of any web application. If writing raw SQL queries, it is a good idea to them readable as well.

Even though SQL special words are case insensitive, it is common practice to capitalize them to distinguish them from table and column names.

• Object oriented Vs. procedural

Object oriented programming can help you create well structured code. But that does not mean you need to abandon procedural programming completely. Actually creating a mix of both styles can be good. Objects should be used for representing data, usually residing in a database.