Tips to Improve Your Code Readability Today

code

Sure, you can probably read your own style of coding now. But what if some other unfortunate person has to work with your terrible, unreadable code? What if you have to go back and look over your old code, a year from now?

I'm sure you'd rather get your work done, instead of spending hours digging around through unreadable code, right?

To save time in the future, you should start to write readable code today.

Whitespace

Whitespace doesn't only apply to design. It should be used to separate certain sections of code from others. Just like in web design, whitespace around parts of code will greatly help to improve readability.

For example, this is very hard to read, right?

function codeReadability($one, $two) {
doStuff(); doMoreStuff();
if($c==$d) {
otherStuff();
} else {
notOtherStuff();
}
}

By adding some line breaks, and by indenting statement blocks, we can make that code possible to read.

function codeReadability($one, $two) {
 
    doStuff();
    doMoreStuff();
 
    if ($c==$d) {
        otherStuff();
    } else {
        notOtherStuff();
    }
 
}

Pretty simple, right? Well, every day I come across snippets of code online that look like the first example. It may be meant to be simply copied and pasted, but I like to be able to look through the code and possibly make some changes to it.

Comments

If you've been programming for more than a week, it has probably been hammered into your head to comment your code. Well, I might hammer it into your head a bit more.

If the purpose of a piece of code isn't immediately recognizable, it could probably benefit from a short comment explaining it.

It is generally a good idea to have a comment at the beginning of each function, to describe what it is used for, and other information about it. A helpful feature of some IDEs is to grab the comments from functions and use them as documentation when referenced elsewhere in the code.

Of course, if a bit of code is self-explanatory, it might not need a comment.

// If $answer is less than 42, increment it by one
if ($answer < 42) {
    // Increment answer by one
    $answer++;
} else { // If $answer is not less than 42
    echo 'The answer is equal to or greater than 42';
}

In this example, those comments are probably a waste of screen real estate.

Naming

There are generally two common styles for naming, camelCase and words_separated_by_underscores.

Whatever style you use, try to use descriptive names. Single-letter variable names are usually a bad idea. For example:

a += b;
c = a + 1;

What are a, b and c? Someone looking through your code shouldn't have to scroll up and down just to figure out what a variable is used for. Here is a better example:

numPeople += numNewPeople;
numPeoplePlus1 = numPeople + 1;

Consistency

There are many different ways of organizing your code, and each way has its own advantages and disadvantages. The important thing is to pick one, and stick with it.

For example, you have to decide whether to use tabs or spaces when indenting your code. Both are generally fine, but you should never mix tabs and spaces.

Another thing that should remain consistent is your indent style. There are many great styles to pick from, so choose one.

My first curly bracket programming language was Java, so I prefer the Java style, with the opening bracket on the same line as the function declaration/control statement/whatever. Choose your own style and stick with it.

If you are working on a project that has a specific style guide that is different from your own, use theirs. You don't want to be that guy that just can't indent his/her code properly.

Line Length

If you've ever had to create a design including more than one line of text, you should probably know that it's best to keep lines under a certain length. In your code, it should be about 80 characters.

Most text editors have a simple feature to show a right margin. Use it, and set it to 80 characters. If your line starts to get longer than that, try to break it off somewhere and continue on the next line, or maybe rethink your code. It will be helpful to anyone using Vim in a terminal, where lines wrap right at the character at the end of the line, possibly breaking a word in half.

Grouping

After keeping statements on separate lines, you should make sure that related lines are kept together, and separated from other groups of lines.

doStuff();
doOtherStuff();
someThing();
anotherThing();
someOtherThing();
doNothing();

In this example, it would be a good idea to separate the functions that have to do with "stuff" from those that have to do with "things" and "nothing".

doStuff();
doOtherStuff();
 
someThing();
anotherThing();
someOtherThing();
 
doNothing();

Conclusion

It is very important for code to be readable, otherwise it just wasts time in the future. Does anyone have more tips for writing readable code?

Stay Updated

Did you enjoy this post? Don't miss a single post by getting free updates!

8 Comments

  1. December 20, 2009

    These are really helpful tips. I myself do some of the rips you have provided here. It proves itself beneficial when debugging. :-)

  2. December 23, 2009

    Really helpful tips... put together in plain words... Thanks for the post.

    -Deepu

Trackbacks/Pingbacks