The Tech Mind

paan 30 July 2008 Articles 2,917 views 9 Comments Print This Post  Email This Post

6 tips to make your fellow coders love you

Code readability is paramount in an environment where you are not the only one reading and writing the code. And even if you are the only developer of your system, I know more than a few coders that read a code that they wrote last week and thought “What the hell was I trying to do with this code?!” So, give your fellow coders a break and follow these 6 tips to make your code readable and make your fellow coders love you.

1.    Consistency

Consistency is the number one rule when writing readable code. It doesn’t matter if you but your braces in the same like as the if statement like this:

1
2
3

if (x==0){
    //do stuff
}

or if it’s on the next line, like this :

1
2
3
4

if (x==0)
{
    //do stuff
}

Just pick one and stick with it. Follow the C++ coding standards or follow the gnu coding standards or follow the java coding standards or make your own standards, it’s up to you, but chooses one and use it everywhere. It’s very annoying to see different kind of coding style in the same project, or worse, the same source file. Create a “Coding Standards.txt” and put it on the top directory of your source code so that all the coders can see that you follow, and expect them to follow, a coding guideline.

2.    Indenting

Indenting is one of the most important aspect of code readability. Indenting allows readers to have a general overview of the flow of the code. And it also provides a visible cue the code’s structure. For me personally, proper(and more importantly consistent) indenting is one of the biggest factor that contributes to code readability. The general rule is that all logic block should be indented, and any logic that branch from the same point should be indented at the same level.

3.    Comments

Many people argue that a lot of comments makes a code readable. But for me the comments should be used sparingly. A well written code should tell its readers what it is doing just by looking at it. Comments should be used however to indicate why a certain part of the code does what it does. For example:

1
2
3
4
5
6
7
8
9
10
11
12

//example 1
i=0;//initialize i
while (i<1000000){//while i is less then 100
	i++;//increment i
}
 
//example 2
//this is part of out test suite to stress the CPU 
i=0;
while (i<1000000){//an arbitaryly long number
	i++;
}

The first example while having more comments is pretty much useless since we already know it is initializing the variable and we already know that it is comparing against a million and we already know that is is incrementing the variable from the code. So the comments add nothing to the understanding of the code. We want to know why it is doing the loop.

The second example solves this by providing a reason for the code to be there and also provide useful information like why the number 1 million is chosen. If you see the code in a production environment then we KNOW that we can remove it because we know what it does. But if we see the first example we might be hesitant to remove it, why is the code here? Does the program require time to finish its task before running the next line and the previous developer never heard of sleep? What is the significant of the number 1 million. Is that the time to live for some unknown cache that we are waiting to expire?

Let the code tells most of the story and what the code can’t tell, you comment.

4.    Variable names

Following my stand that code should obvious and tell its readers what it is doing I believe in descriptive variable naming. I really don’t mind a long variable but numberOfCommentsFromUsersThatAreRegistered is really tiresome to type and read and more likely than not will cause horizontal scrolling on the part of the reader. The basic rule is to be as descriptive as possible but to drop grammatical articles from the variable name. So numberOfCommentsFromUsersThatAreRegistered would become something like registeredUsersCommnetNum. Short forms should be avoided unless it is a really common convention like the prefix is for any function that checks if something is a certain type/condition etc. or the numOf prefix. In strongly typed language like java or C it is common to prefix the name of the variable with the data type. For example intCommentCount is an integer and strVehicleName is a string and so on. Other stuff like underscore use and capitalization shouldn’t matter much but, as per item 1 in this list, pick a style and stick with it.

5.    Minimize horizontal scrolling

When writing code make some effort to minimize horizontal scrolling on your code. The typical screen size is 80 columns and you should try to make sure your code fits this. Horizontal scrolling make it harder to read because of the effort required to actually even see the code. On modern IDE the person reading the code would need to move the mouse to the bottom of the screen and click on the scrollbar. Which is bad enough but then if he needs to read something above or below the code he probably needs to scroll back to see it. On emacs it’s just plain annoying to scroll horizontally. I know there is word wrapping but that always make the code looks bad and ‘wrong’. Most codes can be broken into multiple lines or multiple instructions while keeping the same behaviour.

6.    Follow the gnu convention of doing one thing and doing it right

This apply to writing functions. I always cringe when I see a function called “process” or something like that. Never mind that is it is an ambiguous name to start with, it also implies that the function will do a lot things. For example it might filter the input, then validate it, then store it in the database. It would be much better to create one function to filter the data, another to validate it and another to store it into the database. It is easier to debug that way since we can isolate the processes in the function and also easier to extend because you can, for example, change how the program validate the data without messing with the database code. And more importantly and to the point of this article it is easier to read smaller chunks of code that you know is doing a single thing that to plow through a whole page of code that could be doing either of the three things mention.

The End

Now go write your code and make your fellow coders love you.