Coding conventions - PHP

As with your physical application, the logical application should also adhere to standard conventions. Classes, functions, variables and constants should all be named and formatted in a consistent manner that clearly and concisely conveys intent. Since we are discussing the logical application now, otherwise known as code, let’s go to a few examples. First, we will see an example of code that simply fails to adequately convey intent and lacks readability.

 <?php
 $_X = foo(2);
 print $_X;
 
 function foo($bar) {
 return $bar * $bar; }
 ?>

While this example is quite academic in nature, the point is made. The variable “$X” and the function “foo” do nothing to convey their intent – you must actually read the code inside of the function to know what will be displayed by this script. Imagine the function “foo” containing a complex algorithm and returning various codes if errors are encountered. You would have to work through the function line by line to determine exactly what is going on.

This example also displays very poorly formatted code in the function “foo”, making it somewhat difficult to look at. Additionally, the uppercasing of the variable “$X” puts the variable into the same formatting space as constants and superglobal variables in PHP, making it appear as if it were simply typed incorrectly. Consider now the improved version of our example.

 <?php
 $myNumber = 2;
 $mySquaredNumber = square($myNumber);

 function square($number)
 {
  return $number * $number;
 }
 ?>

Not only is this example easier to read, but the variables and the function name are clear, and it is obvious what the code is going to do without even reading the function defintion. Variables in this example are formatted with camel caps, just like files and directories in our application. This makes them easy to read and easy to type. Curly braces in our function definition appear on their own lines, improving the readability of the function and clearly encapsulating the code within them. Additionally, code directly following a curly brace should always be indented one tab space until the next closing curly brace. Let’s now expand our examples to see a second comparison. Afterward we will review our fundamental code formatting rules in list form.

 <?php
 print new foo_class(2);
 
 class foo_class{
 function foo_class($foo) { return $foo * $foo; }}
 ?>

This example is bad in even more ways than the first. To begin with, using a class instance in static context is wasteful. The class name does not give any hint as to what its purpose is, nor does the constructor method that is used to return the square of a given number. Again, this example is obviously academic but I’m absolutely certain that most PHP developers have seen code of this nature in the real world – it is never pretty to look at or maintain. Now, consider this revision.

 <?php
 $myNumber = 2;
 $myNumberSquared = Math::square($myNumber);
 print $myNumber;
 
 class Math
 {
  function square($number)
  {
   if (is_numeric($number) == false)
   {
    return 0;
   }
   
   return $number * $number;
  }
 }
 ?>

This example takes up a lot more screen space but it is infinitely easier to look at. Again, our variables have clear names that indicate their purpose. Our class, unlike variables and functions, begins with a capital letter. Classes should use the camel caps format with an upper case first letter – this makes it clear when seen in code that a class is being referenced and it also logically denotes the classes position in the heirarchy of the application, literally appearing at a higher level than functions.

The code within the class is neatly indented and all curly braces appear on their own lines, making blocks of code nested inside one another easy to distinguish. This example even adds some basic error checking to be certain that the parameter “$number” is actually a number. Note that we do a proper test on the return value of our call to “is_numeric”, avoiding the use of short-circuit boolean logic. I will return to this point later.

To sum up our coding conventions, here is a simple list of rules.

1. Variables should be given appropriate names and use the camel caps format.
   
2. Class names should be given appropriate names and use the camel caps format with the first letter capitalized.
   
3. Function names should also use the camel caps format, like variables, and should have appropriate names. Function parameters should also be named appropriately. These same rules apply to class methods.
   
4. Curly braces should appear on lines by themselves and code inside them should be indented one tab space.
   
5. Constants should appear in all capital letters.
   
6. Class variables should be given appropriate names, use the camel caps format, and begin with an underscore. Class variables should never be accessed from outside of the class, and using the underscore allows us to code functions with the same name as class variables without problems. In PHP 5, this is less of a stylistic issue because you can actually specify method and variable visibility.
   
7. Classes, functions and variables should never be named redundantly. That is, a function should not be named “fn_square” and a class should not be named “MathClass.”

Those six rules cover the fundamentals of stylistic coding conventions. Adhering to these conventions, whether you adhere to them exactly as described or make small changes to suit your style, will greatly improve the readability of code.

>>> More PHP Articles          >>> More By David Fells

blog comments powered by Disqus