PHP

Practical Code Refactoring, Part 2 – Readability

    Abdullah Abouzekry
    Share

    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.

    General

    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.

    Naming

    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.

    Expressions

    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.

    Summary

    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