Practical Code Refactoring, Part 2 – Readability

Share this article

In part one of this series I introduced what constitutes good code. As the series on code refactoring continues we’ll dive into each of the three aspects and see how to refactor for each of them in order: readability, extensibility, and efficiency. In this part, the focus is on refactoring your code for better readability. Recall the definition of readability: readable code follows some well-known style and documentation practices. To help you start refactoring your code for readability, I’ve prepared this list of questions you should ask yourself throughout the development, testing, and review process.


1. Does the code follow a standard guideline for style, syntax, and documentation? You should be using a coding standard, preferably a public one like PSR-1/2. For any common practice that is not defined in the standard and you are enforcing in your code, write a brief note on it for yourself and your team. 2. Are you using standard syntax for constructs, or an alien syntax? In PHP you may have several styles for writing various constructs (like PHP alternative syntax for control structures). If you are using alien syntax, for example using the alternative syntax only inside HTML templates and the C-style syntax in standard code, document this to avoid ambiguity. Better yet, stick to only one style. I prefer using the C-style syntax throughout all of my projects and avoid alien syntax all together. 3. Does each file have a header comment documenting its role in the project? As a minimum, you should include a header comment with the following in each code file:
  • Application name, version, and a brief description.
  • File relation to other files and to which package/group it belongs if any.
4. Is global code kept to a minimum? Global code is fine for quick scripting and single-file solutions, but when you build complex web applications, global code can become your biggest headache. Keep it to a minimum as much as possible. If global code contains blocks other than functions and class definitions, like control structures, then you should refactor your code into functions or classes as well. As a general rule of thumb, don’t include control structures in global code.


1. Do the names of your classes, variables, etc. follow a standard pattern/style throughout your code? Variables, constants, functions, methods, classes, and namespaces should all follow a unified style of naming for over the whole code base, and would likely be part of the general coding standard you are using else you need to enforce it. 2. Are names meaningful and unambiguous? The names you use for variables, functions, etc. should be meaningful. Don’t create names like $abc
, rather use names like $count, getFile() which are good and understandable. An exception to this would be variables with well-known behavior, such as counter variables $i/$j/$k in a loop. 3. Are names too long or too short? Variable names and constants should be on average around 8-12 character long. Some exceptions might reach 25 chars, but more than that is unreadable and cumbersome, so if you have any which are very long (or very short) then you should rethink its usage. Thinking about usage helps craft better names. The names of methods/functions should be on average around 15-25 character long, though some exceptions might reach 30. As with variable names, you should re-think any longer/shorter ones. Class names should be as short as possible and expressed as nouns. If you are following a coding standard then follow its conventions for classes, otherwise your class name should be around 10-15 chars.


1. Do expressions follow a standard pattern/style? How you write expressions and format them is crucial for code readability. Some prefer to add a space before and after operators, like $counter = 15; while some pefer no space at all. Whichever you choose, be consistent throughout all of your code. 2. Are expressions easy to understand, or are they too complicated?
For too complicated/too long expressions, split the expression across multiple lines. As a general rule, if your expression contains three or more different operands, you should probably write a comment for it for the sake of understanding it in the future. Of course, updating the comment when you update the expression is important, too. Don’t miss that! :)

Code blocks

1. Do code blocks follow a standard pattern/style? Code blocks are the basic building blocks of your code base. You should review how each should look before writing a single line and stick to that since the human eye is more sensitive to style than the content itself. Stick to your standard on where to put brackets, spaces, etc. Your eyes will read through the constructs faster when regular rules are applied and you’ll be able to understanding it easier. 2. Are blocks longer than 20-25 lines on average? If your code blocks are longer than 30 lines, I would recommend refactoring it at least once, though you may need to refactor more than a single iteration to get better code. Some exceptions might reach 50 lines or a bit more, but they are still exceptions and shouldn’t be habit. Longer code isn’t as readable; small chunks of code are more readable and maintainable than large ones. 3. Are code blocks well commented to explain what functionality they add? In perfect code, each code block should say in words what it achieves in code. Keep this as a rule, but we all know that life’s not perfect so you might just need to do this for code blocks which are longer than the average (more than 20-25 lines), or any which perform a complex task. This is left to your sense, but I myself prefer adding a single line comment before any block briefing the future-reader of its intention, unless it’s trivial.


Now you can start refactoring code to make it more readable using this article as a checklist as a starting point. There’s no excuse for your code to not always be in a healthy state regarding readability. I would even recommend you put these questions in a spreadsheet along with your source code and schedule refactoring tasks based on it, or just use it whenever you feel like your code is not healthy. In the upcoming parts of we’ll focus on refactoring for extensibility and efficiency. Stay tuned! Image via Fotolia

Frequently Asked Questions (FAQs) about Code Refactoring

What are the key benefits of code refactoring?

Code refactoring is a crucial process in software development that offers numerous benefits. Firstly, it improves the design of software, making it more efficient and easier to understand. This, in turn, makes the software easier to maintain and extend in the future. Secondly, it helps in finding bugs and correcting them, thereby enhancing the overall quality of the software. Lastly, refactoring can make the software more adaptable to changes, which is essential in the rapidly evolving tech industry.

How often should code refactoring be done?

The frequency of code refactoring depends on several factors such as the complexity of the project, the quality of the initial code, and the changes in requirements. However, it is generally recommended to refactor code continuously during the development process. This helps in maintaining the quality of the code and makes it easier to incorporate changes.

What are the risks associated with code refactoring?

While code refactoring has numerous benefits, it also comes with certain risks. The most significant risk is the possibility of introducing new bugs into the system. This can be mitigated by using automated testing tools and following best practices for refactoring. Another risk is the time and resources required for refactoring. It is important to balance the need for refactoring with the need to deliver the product on time.

What are some best practices for code refactoring?

Some best practices for code refactoring include: understanding the code thoroughly before starting the refactoring process; making small, incremental changes and testing after each change; using automated testing tools to ensure that the functionality of the code is not affected; and documenting the changes made during the refactoring process.

How does code refactoring contribute to Agile development?

Code refactoring is a key component of Agile development. In Agile, the requirements are constantly changing, and the code needs to be adaptable to these changes. Refactoring helps in making the code more flexible and easier to modify. Moreover, Agile emphasizes on delivering high-quality software, and refactoring contributes to this by improving the design and reducing the bugs in the software.

What tools can be used for code refactoring?

There are several tools available for code refactoring, such as ReSharper, SonarQube, and JRefactory. These tools provide automated refactoring capabilities, which can significantly reduce the time and effort required for refactoring. They also provide features like code analysis and code metrics, which can help in identifying the areas of the code that need refactoring.

What is the role of testing in code refactoring?

Testing plays a crucial role in code refactoring. It ensures that the functionality of the code is not affected by the changes made during the refactoring process. Automated testing tools can be particularly useful in this regard, as they can quickly identify any issues introduced by the refactoring.

How can code refactoring improve code readability?

Code refactoring can significantly improve code readability by simplifying the code structure, removing redundant code, and improving the naming conventions. This makes the code easier to understand and maintain, which is particularly important in large projects where multiple developers are involved.

Can code refactoring be automated?

Yes, code refactoring can be automated to a certain extent using tools like ReSharper and SonarQube. These tools can automatically identify areas of the code that need refactoring and suggest appropriate changes. However, it is important to note that automated refactoring should be complemented with manual review to ensure the quality of the code.

What is the difference between code refactoring and code rewriting?

Code refactoring involves modifying the internal structure of the code without changing its external behavior, with the aim of improving its quality and maintainability. On the other hand, code rewriting involves completely rewriting the code from scratch. While refactoring is generally preferred due to its lower risk and cost, rewriting may be necessary in some cases where the code is too complex or outdated to be refactored effectively.

Abdullah AbouzekryAbdullah Abouzekry
View Author

Abdullah Abouzekry is an experienced web-developer with over 7 years developing PHP/MySQL applications ranging from simple web sites to extensive web-based business applications. Although his main experience is with PHP/MySQL and related web technologies, he has developed and localized many desktop applications in C#, Python/Qt, Java, and C++. When not writing code, Abdullah likes to read, listen to oriental music, and have fun with his little family.

Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week