Blog

As I have been going through different code bases, I keep seeing things that just really amaze me. It all surrounds coding standards, or the lack thereof. Different places have different ideas of what is best, and I can only offer mine to the fray. However, once a standard is in place, no matter how odd it may be, it is important to keep to those standards. This is for a few reasons.

First, it is important for readability. By seeing the code in the same format and structure it helps to get through lines of code quickly. It helps because all of the code is in the same format throughout the code. The person looking at the code can quickly understand without having to go back and figure out what is happening because the code is all of a sudden out of whack and what you may think is happening may not be happening. Especially when indentation may also be out of line and brackets are not used. Take for example the two examples below

$fin=0;
foreach($var as $v){
if($v==3){$fin=$v+3}
unset($fin);echo $v; 
}

As a stand alone example it may be easy to decipher what is happening. In a file that has over 3000 lines of code, it may be overlooked and even cause issues if changes are made that affect that block. By breaking from the set coding standards and doing it “your own way”, sure it may be quicker for you, but it creates havoc, even for you later on.

Second, it is about cleanliness. Using the same block of code above, that looks absolutely horrid to me. I know some people code this way because “it takes up less space”, some even make a claim that it makes the code process faster. To that point, if you need to cut down on whitespace in the code in order to get the application to go faster, then maybe you ought to look at the code again, because it is likely something else that is causing problems, not the whitespace. If that code block again had been done with a few standards in place, it could look like this instead:

$fin = 0;
foreach ( $var as $v ) {
    if ( $v == 3 ) {
        $fin = $v + 3;
    }
	
    unset($fin);
    echo $v; 
}

By doing this, the code looks cleaner, which adds to its readability. Clean code not only looks good, but is very easy to do. It helps to maintain the flow of work, especially in larger projects. By sticking to a clean code standard, all developers can jump in at any time and pick up easily, as everything is nicely placed, and easy to understand. There will be times when you write some code, then do not touch it for months, maybe years, and have to go back to review something. You will be very glad if you kept to standards and kept your code clean.

Third, it is about working in the team. If you are alone in the project, then great. You get to choose how you want to work. Most times it is more than just you, so it is important that everyone works in the same standards. This can be up to the team to determine. This can include spacing, indentation, bracket use, variable naming conventions, ternary use, etc. But whatever the team decides, stick to it. Do not be a rogue and do it your own way just because you think it is better. Having the code in a standardized format really, really helps in the long run. Teams are able to debug code quicker because they do not have to decipher different standards. Coding can happen in a dynamic environment where you may be working on a data object one day, then have to switch to help with the controller layer the next. You will not have to go through the code and decipher the different styles.

With that being said, some of the standards that I use may not work for everyone. I am a little neurotic and OCD when it comes to code, so I like a specific style, but can adapt as needed. Here are some of the things I use:

• Variables names must be descriptive of what they represent, the only exception being is for counters/iterators
  for example, a variable for total amount would be $total, or the variable for tax would be $tax, or the variable for a unique identifier would be $uid.

• For loops, If and Switch statements must be bracketed, must have spaces between the parenthesis, and must be indented. The length of indentation I usually use 4 spaces (or set the tab stops to 4 spaces). Switch statements must have indentations for each case. Example:

  if ( $var = 0 ) {
      // do something
  }
  
  for ( $c = 0; $c <=5; $c++ ) {
      // do something
  }
  
  switch ( $var ) {
      case 1:
          // do something
          break;
      case 2: 
          // do something
          break;
      default:
          // do something
  } 

  There should never be any If statement or loop that is never bracketed, ever. I think that is lazy coding, I think it looks atrocious, and when more code is needing to be added to the struct, it causes more time wasted to ensure that the proper items are included.

• Functions should be bracketed, and indented, even if it is only one line of code in the function. Comments should also be done on every function describing the purpose of the function.
• Comments describing functions/objects/classes should follow the same format. If PHPDoc is used, then use it throughout. Do not change the way you comment these. I have seen functions in a file commented using PHPDoc, using the "// ----- description", and then surrounded by "//" around the entire comments. I really do not care which one to use, but when one is decided to be used, use only that.
• Never, ever use short tags, or short echo tags. They are just bad form, another example of lazy coding, and will cause problems here soon. Even though PHP6 is all but dead, the "enhancement" to remove short tag/short echo tag will make it to a release here soon. I understand the old PHP4 was all over it, but should not have been. Use the full tag and do not use "<?=" to echo something out.
• Do not just copy and paste code to other parts of the application. If you find that a code block can be re-used in other areas, then wrap it in a function, or an object/class, and keep the code centralized. When the code needs to be updated, you then only have to update one section, instead of multiple files.

OK, so my rant is over. The list above is my standards. This may not always work in every project. Some of the good areas to look at for ideas or practices for code standards are:
http://pear.php.net/manual/en/standards.php
http://framework.zend.com/manual/en/coding-standard.html
https://trac.cakephp.org/wiki/Developement/CodingStandards

Most of the standards I use are located in these documents.