7 tips to write intelligible code

Writing intelligible code helps to increase the productivity of a developing team, even if you are an independent worker. Why is it so important to write intelligible code? How can it improve the productivity of my team? A messed up code could delay your partners understanding, or it could create a barrier for new developers. Even trying to understand your own code could be a real challenge as well. Here are 7 tips of how to make more intelligible PHP code (coding style tips):

1. 75-85 characters per line: Each line must contains approximately 75-85 characters. If a line exceeds more than 85 characters, consider splitting the line into multiple lines. It will be helpful for code readability. You can see a great post on this topic in Paul Jones’ blog. He talks about why this limitation is not really arbitrary, and he puts some brilliant examples such as this one:

   Bad

   list($foo, $bar, $baz) = array(Zim::getVal('foo'), Dib::getVal('bar'), Gir::getVal('baz', Gir::DOOM));
   

   Good

   $foo = Zim::getVal('foo');
   $bar = Dib::getVal('bar');
   $baz = Gir::getVal('baz', Gir::DOOM);
   

2. Assignment statements: Assignment statements ought be aligned for better readability. Let’s see an example:

   Bad

   
   $example = 'string_value';
   $anotherExample = 42;
   $exampleInst = new ExampleClass();
   

   Good

   
   $example        = 'string_value';
   $anotherExample = 42;
   $exampleInst    = new ExampleClass();
   

3. 4-spaces block indentation: Use an indent of 4 spaces with no tabs. It helps to avoid problems with diffs, patches and SVN history. It helps the readability as well. Usually tabs are 8 spaces length, which means a 5th-block indent starts 40 spaces from the left border (nearly to 50% of a code line).
   

   
   {block1}
       {block2}
           {block3}
               ...
   
   

4. Control & conditional structures: These statements must have one space between the control keyword (if, else, for, while, …) and the opening parenthesis, to distinguish them from function calls (which obviously don’t have a space). It’s nice to always use curly braces because they help to decreases the likelihood of logic errors.

   
   if ($display === 1) {
       while ($obj->next()) {
           echo $obj->toString();
       }
   }
   
   

5. Class and function/methods declarations: Class and function/methods declarations have their opening brace on a new line.

   
   class Foo
   {
       private $_obj;
   
       public function __construct($obj)
       {
           $this->_obj = $obj;
       }
   }
   

6. Comma-space between items of a list: When we list some items, it’s nice to separate them clearly with a comma followed by a space.

   BAD

   
   $example = array(Foo::get('key',2),$value,true);
   

   GOOD

   
   $example = array(Foo::get('key', 2), $value, true);
   

7. Use constants properly: If we have a method which returns some status codes, it’s nice to use literal constants. Having descriptive constants helps to make better intelligible code. For example:

   BAD

   
   class Foo
   {
       public static function getStatus()
       {
           $res = 0;
   
           if (!self::isValid()) {
               $res = 1;
           }
           ...
   
           if ($res === 0 && self::isRepeated()) {
               $res = 2;
           }
   
           return $res;
       }
   }
   

   GOOD

   
   class Foo
   {
       const STATUS_SUCCESS  = 0;
       const STATUS_FAILURE  = 1;
       const STATUS_REPEATED = 2;
   
       public static function getStatus()
       {
           $res = self::STATUS_SUCCESS;
   
           if (!self::isValid()) {
               $res = self::STATUS_FAILURE;
           }
   
           ...
   
           if ($res === self::STATUS_SUCCESS && self::isRepeated()) {
               $res = self::STATUS_REPEATED;
           }
   
           return $res;
       }
   }
   

These tips are just some coding style tips. If we really want to write intelligible code, we would keep in mind many more things like to use software patterns, to make use of well established software practises, …