One of the main challenges faced by both beginners and advanced programmers is how to improve their code writing style to make it more readable and maintainable. In this post, you will find a list of 7 typical problems that programmers may face along with the simplest methods to solve these problems. These problems are, in fact, code misuses that are introduced to the code by the programmer himself, and their eradication may greatly improve the readability, maintainability, and usability of the code that the programmer writes

Problem #1: Not using functions

Problem: Not using functions is a characteristic problem for PHP programmers, especially early on in their careers. The problem stems from the fact that a programmer can write dozens of lines of PHP scripts without having to wrap the parts of the code in functions. This is problematic because it is difficult to understand what the code actually does without delving deeply into it, and the programmer may repeat himself unintentionally.

Solution: The solution is to divide the code into individual functions.

Problem #2: Not using PHP built-in functions

Problem: We need a function to solve a common problem, and we try to write it ourselves instead of looking for an existing function that provide the functionality that we need.

Solution: PHP offers hundreds of useful functions which eliminate the need to “reinvent the wheel”, and will often do the job much more efficiently than anything that a standard programmer writes. So, if you come across the need to write complex functions that you think may already exist, it is best to search the Internet (and the PHP documentation in particular) before embarking on writing your own code.

Problem #3: Vague names for functions and variables

Problem: Another problem that appears even among experienced programmers is that of vague and incomprehensible variable and function names. For example, a function name like “doSomething” is much too vague. The problem may be due to several reasons: lack of awareness, laziness, or the result of a function that had been written to serve a specific action, but which ended up doing another action instead. This problem contributes to the reduction in code readability and adds to the difficulty in maintaining and modifying the code.

Solution: The solution is to give functions and variables accurate and descriptive names that contain 2 to 3 words or more.

Problem #4: Magic numbers and strings

Problem: A magic number is a number that is found in the code which has no explanation or name. For example, the number 5 in the following code example is a magic number: for($i = 0; $i < 5; $i++) {   //do check }

It is unclear why the code should run 5 times.

Solution: To make the code more readable, we better give the variable a descriptive name. For example:

$numberOfChecks = 5;

for($i = 0; $i < $numberOfChecks; $i++)
{
  //do check
}   

Similarly, magic strings are strings that appear in the code without any explanation and, in their case also, it is recommended to set the name of a variable as a descriptive name.

Problem #5: Code duplication

Problem: If you find yourself writing the same code over and over again, there is something wrong with your code. Moreover, when you behave in such a way, you violate one of the most important principles of writing modern code: Do not repeat yourself (DRY). The reason why the DRY principle is so important is simple and practical. Imagine if, after you have finished writing the code, you have to change something. If you’re not fastidious enough and have written the same code more than once, you’ll have to make an effort to change the code in several places which can contribute to the emergence of bugs. However, if you make sure you don’t repeat yourself, you will have to change the code in only one place.

Solution: The best way to avoid duplicate code is to wrap the code in functions and then call whatever function you need from wherever you need it.

Problem #6: Functions that do more than one thing

An effective function should ideally do only one thing

An effective function should ideally do only one thing so that we can call it from different places in the code knowing with full confidence that it will only do exactly what it is supposed to do, and nothing else. Therefore, care should be taken that any function you write has only a single responsibility.

Problem #7: Too many nested conditions

Problem: One of the main problems that cause the code to be messy and hard to read is that of too many nested conditions (i.e. an if statement within another if statement).

Solution: We can solve the problem of nested conditions by making use of functions and the return command.

For example:

function eliminateNestedConditionals($string)
{
  if($string==='a') return "a indeed";
    
  if($string==='b') return "b";
    
  return "x";
}

$string = "m";

echo eliminateNestedConditionals($string);