10 Tips for Improving the Readability of Your Code

Making your code easier to read will also help you debug your own programs, making it easier on yourself.

Code readability is a universal subject in the world of computer programming. It's one of the first things we learn as developers. This article will detail the most important best practices when writing readable code.

1 - Commenting and Documentation

IDEs (Integrated Development Environments) have come a long way in the past few years. They've made commenting your code easier than ever. Following certain standards in your comments allows IDEs and other tools to utilize them in different ways.

Consider this example:

The comments I added at the function definition can be previewed whenever I use that function, even from other files.

Here is another example, where I call a function from a third party library:

In these particular examples, the type of commenting (or documentation) used is based on PHPDoc, and the IDE is Aptana.

2 - Consistent Indentation

I assume you already know that you should indent your code. However, it's also worth noting that it is a good idea to keep your indentation style consistent.

There is more than one way of indenting code. Here are two of the more common:

Style 1:

function foo() {
    if($maybe){
        do_it_now();
        again();
    } else{
        abort_mission();
    }
    finalize();
}

Style 2:

function foo(){  
if($maybe) {  
 do_it_now();
        again();
    }else{  
 abort_mission();
    }
    finalize();
}

I used to code in style #2 but recently switched to #1. But that is only a matter of preference. There is no "best" style that everyone should be following. Actually, the best style is a consistent style. If you are part of a team or if you are contributing code to a project, you should follow the existing style that is being used in that project.

The indentation styles are not always completely distinct from one another. Sometimes, they mix different rules. For example, in PEAR Coding Standards, the opening bracket "{" goes on the same line as control structures; but, they also go to the next line after function definitions.

PEAR Style:

function foo()
{ //placed on the next line
    if($maybe) { // placed on the same line
        do_it_now();
        again();
    } else {
       abort_mission();
    }
    finalize();
}

Also, note that they are using four spaces instead of tabs for indentations.

Here is a Wikipedia article with samples of different indent styles.

3 - Avoid Obvious Comments

Commenting your code is fantastic; however, it can be overdone or just be plain redundant. Take this example:

// get the country code
$country_code = get_country_code($_SERVER['REMOTE_ADDR']);
// if country code is US
if ($country_code == 'US'){
// display the form input for state
echo form_input_state();
}

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 into a single line instead:

// display state selection for US users
$country_code = get_country_code($_SERVER['REMOTE_ADDR']);
if ($country_code == 'US'){
echo form_input_state();
}

4 - Code Grouping

More often than not, certain tasks require a few lines of code. It is a good idea to keep these tasks within separate blocks of code, with some spaces between them.

Here is a simplified example:

// get list of forums
$forums = array();
$r = mysql_query("SELECT id, name, description FROM forums");

while ($d = mysql_fetch_assoc($r)){
$forums[] = $d;
}

// load the templates
load_template('header');
load_template('forum_list', $forums);
load_template('footer');

Adding a comment at the beginning of each block of code also emphasize the visual separation.

5 - Consistent Naming Scheme

PHP itself is sometimes guilty of not following consistent naming schemes:

• strpos() vs. str_split()
• imagetypes() vs. image_type_to_extension()

First of all, the names should have word boundaries. There are two popular options:

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

Having different options creates a situation similar to the indent styles, as I mentioned earlier. If an existing project follows a certain convention, you should go with that. Also, some language platforms tend to use a certain naming scheme. For instance, in Java, most code uses camelCase names, while in PHP, the majority of coders use underscores.

These can also be mixed. Some developers prefer to use underscores for procedural functions, and class names, but use camelCase for class method names:

classFoo_Bar{
publicfunctionsomeDummyMethod(){
}

So again, there is no obvious "best" style. Just being consistent.

6 - DRY Principle

DRY stands for Don't Repeat Yourself. Also known as DIE: Duplication is Evil.

The principle states:

"Every piece of knowledge must have a single, unambiguous, authoritative representation within a system."

The purpose for most applications (or computers in general) 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.

For example, most web applications consist of many pages. It's highly likely that these pages will contain common elements. Headers and footers are usually best candidates for this. It's not a good idea to keep copy-pasting these headers and footers into every page. Here is Jeffrey Way explaining how to create templates in CodeIgniter.

$this->load->view('includes/header');   
$this->load->view($main_content);   
$this->load->view('includes/footer');

7 - Avoid Deep Nesting

Too many levels of nesting can make code harder to read and follow.

functiondo_stuff(){
// ...
if (is_writable($folder)){
    if ($fp = fopen($file_path, 'w')){
        if ($stuff = get_some_stuff()){
            if (fwrite($fp, $stuff)){
// ...
   }
      else
   {
    returnfalse;
   }
  }
  else
{

For the sake of readability, it is usually possible to make changes to your code to reduce the level of nesting:

functiondo_stuff(){
// ...
if (!is_writable($folder)){
returnfalse;
}
if (!$fp = fopen($file_path, 'w')){
returnfalse;
}
if (!$stuff = get_some_stuff()){
returnfalse;
}
if (fwrite($fp, $stuff)){
// ...
}
  else
{
returnfalse;
}
}

8 - Limit Line Length

Our eyes are more comfortable when reading tall and narrow columns of text. This is precisely the reason why newspaper articles look like this:

It is a good practice to avoid writing horizontally long lines of code.

//bad
$my_email->set_from('test@email.com')->add_to('programming@gmail.com')->set_subject('Methods Chained')->set_body('Some long message')->send();   
// good
$my_email   
->set_from('test@email.com')    
  ->add_to('programming@gmail.com')    
  ->set_subject('Methods Chained')   
  ->set_body('Some long message')   
  ->send();   
// bad
$query= "SELECT id, username, first_name, last_name, status FROM users LEFT JOIN user_posts USING(users.id, user_posts.user_id) WHERE post_id = '123'";   
// good
$query= "SELECT id, username, first_name, last_name, status    
  FROM users   
  LEFT JOIN user_posts 
  USING(users.id, user_posts.user_id)    
  WHERE post_id = '123'";

Also, if anyone intends to read the code from a terminal window, such as Vim users, it is a good idea to limit the line length to around 80 characters.

9 - File and Folder Organization

Technically, you could write an entire application's code within a single file. But that would prove to be a nightmare to read and maintain.

During my first programming projects, I knew about the idea of creating "include files." However, I was not yet even remotely organized. I created an "inc" folder, with two files in it: db.php and functions.php. As the applications grew, the functions file also became huge and unmaintainable.

One of the best approaches is to either use a framework or imitate their folder structure. Here is what CodeIgniter looks like:

10 - Consistent Temporary Names

Normally, the variables should be descriptive and contain one or more words. But, this doesn't necessarily apply to temporary variables. They can be as short as a single character.

It is a good practice to use consistent names for your temporary variables that have the same kind of role. Here are a few examples that I tend to use in my code:

// $i for loop countersfor
($i= 0; $i< 100; $i++) {       
  // $j for the nested loop counters    
  for($j= 0; $j< 100; $j++) {       
  }
}   
// $ret for return variables
functionfoo() {    
 $ret['bar'] = get_bar();    
 $ret['stuff'] = get_stuff();       
 return$ret;
}   
// $k and $v in foreachforeach
($some_arrayas$k=> $v) {   
}   
// $q, $r and $d for mysql
$q= "SELECT * FROM table";
$r= mysql_query($q);
while($d= mysql_fetch_assocr($r)) {  
}   
// $fp for file pointers\
$fp= fopen('file.txt','w');