# Top 18 Best Practices for Writing Super Readable Code

Code readability is fundamental for development—it is key to maintainability and working together with a team. This article will detail the 18 most important best practices when writing readable code.

## 1. Commenting & Documentation

IDEs (Integrated Development Environments) and code editors have come a long way in the past few years. This has made commenting your code more useful 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 to 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 Visual Studio Code.

## 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's more than one way of indenting code.

#### Style 3

 1 function foo()  2 { if ($maybe)  3  { do_it_now();  4  again();  5  }  6  else  7  { abort_mission();  8  }  9  finalize();  10 }  I used to code in style 2 but recently switched to style 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 go to the next line after function definitions. PEAR Style:  1 function foo()  2 { // placed on the next line  3  if ($maybe) { // placed on the same line  4  do_it_now();  5  again();  6  } else {  7  abort_mission();  8  }  9  finalize();  10 } 

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

On Wikipedia, you can see samples of different indent styles.

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

 1 // get the country code  2 $country_code = get_country_code($_SERVER['REMOTE_ADDR']);  3 4 // if country code is US  5 if ($country_code == 'US') {  6 7  // display the form input for state  8  echo form_input_state();  9 }  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:  1 // display state selection for US users  2 $country_code = get_country_code($_SERVER['REMOTE_ADDR']);  3 if ($country_code == 'US') {  4  echo form_input_state();  5 } 

Comments should ideally explain why you were doing something the way you did it. If you have to write more than a one-line comment to explain what the code is doing, you should consider rewriting the code to be more readable.

## 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:

## 11. Capitalize SQL Special Words

Database interaction is a big part of most web applications. If you are writing raw SQL queries, it is a good idea to keep them readable as well.

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

 1 SELECT id, username FROM user;  2 3 UPDATE user SET last_login = NOW()  4 WHERE id = '123'  5 6 SELECT id, username FROM user u  7 LEFT JOIN user_address ua ON(u.id = ua.user_id)  8 WHERE ua.state = 'NY'  9 GROUP BY u.id  10 ORDER BY u.username  11 LIMIT 0,20 

## 12. Separation of Code and Data

This is another principle that applies to almost all programming languages in all environments. In the case of web development, the "data" usually implies HTML output.

When PHP was first released many years ago, it was primarily seen as a template engine. It was common to have big HTML files with a few lines of PHP code in between. However, things have changed over the years, and websites have become more and more dynamic and functional. The code is now a huge part of web applications, and it is no longer a good practice to combine it with the HTML.

You can either apply the principle to your application by yourself, or you can use a third-party tool (template engines, frameworks, or CMSs) and follow their conventions.

## 13. Alternate Syntax Inside Templates

You may choose not to use a fancy template engine, and instead go with plain inline PHP in your template files. This does not necessarily violate the "Separation of Code and Data," as long as the inline code is directly related to the output and is readable. In this case, you should consider using the alternate syntax for control structures.

Here is an example:

 1 
 2   3  Hello, username; ?>
 4   5   6  |  7   8   9 
 10 11 

My Message Board

 12 13   14 15 
 16 17 

title; ?>

 18 19  Forums as $forum): ?>  20 21   22 23   24  id,$forum->title) ?>  25  (Threads->count(); ?> threads)  26 

 27 28 
 29  description; ?>  30 
 31 32 
 33 34   35 36 
 37 38  

This lets you avoid lots of curly braces. Also, the code looks and feels similar to the way HTML is structured and indented.

## 14. 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.

 1 class User {  2 3  public $username;  4  public$first_name;  5  public $last_name;  6  public$email;  7 8  public function __construct() {  9  // ...  10  }  11 12  public function create() {  13  // ...  14  }  15 16  public function save() {  17  // ...  18  }  19 20  public function delete() {  21  // ...  22  }  23 24 } 

Procedural functions may be used for specific tasks that can be performed independently.

 1 function capitalize($string) {  2 3 $ret = strtoupper($string[0]);  4 $ret .= strtolower(substr($string,1));  5  return$ret;  6 7 } 

Open-source projects are built with the input of many developers. These projects need to maintain a high level of code readability so that the team can work together as efficiently as possible. Therefore, it is a good idea to browse through the source code of these projects to observe what these developers are doing.

## 16. Use Meaningful Names for Variables and Functions

You will save a lot of your precious time by using meaningful names for variables and functions. This may not seem like a big deal when you are just starting out and the programs you write are just a couple of dozen lines long. However, things get very confusing fairly quickly for code that has hundreds or thousands of lines.

Consider an example, where you have two variables $is_vaccine_available and $iva. In a large program, it won't be easy to guess what purpose $iva serves without looking through some relevant lines of code. On the other hand, you can guess that the variable $is_vaccine_available is almost certainly being used to store the status of vaccine availability.

Trying to save time by using very short names for variables and functions is counter-productive in the long run, especially when there are a lot of capable code editors and IDEs available to help you write code.

## 17. Avoid Using Magic Numbers

The concept of magic numbers in programming refers to the use of hard-coded numerical values in your code. Using such numbers might make sense to you while you are writing the code. However, you or someone else will most probably have a hard time figuring out what that number was supposed to do when they look at the same piece of code in future.

 1  400) {  4  // Do something  5 }  6 7 $container_capacity = 400;  8 while($egg_count > $container_capacity) {  9  // Do Something  10 }  11 ?>  Considering the code above, in the first case, we have no idea what the 400 signifies. Is it the count of people who will be served eggs, or is it something else? On the other hand, we know very clearly in the second case that we are checking if our egg count is over the container capacity. It is also easier to update the $container_capacity by changing its value in one place. This will not be possible when using magic numbers as you will have to go through the whole code.

## 18. Code Refactoring

When you "refactor," you make changes to the code without changing any of its functionality. You can think of it like a "cleanup," for the sake of improving readability and quality.

This doesn't include bug fixes or the addition of any new functionality. You might refactor code that you have written the day before, while it's still fresh in your head, so that it is more readable and reusable when you may potentially look at it two months from now. As the motto says: "refactor early, refactor often."

You may apply any of the "best practices" of code readability during the refactoring process.

## Conclusions

I hope you enjoyed this article! Code readability is a huge topic, and it's well worth thinking more about, whether you work alone, with a team, or on a large open-source project.

This post has been updated with contributions from Monty Shokeen. Monty is a full-stack developer who also loves to write tutorials and to learn about new JavaScript libraries.