15 Nov 2010

Hiring a PHP Programmer: Part #2, Code Organization & Commenting 

By - PHP 2 Comments

In part #1 of our short series on hiring a quality PHP programmer, we spoke about SQL injection security. In today’s post we are going to look at an outwardly less important but crucial aspect to any programmer: what their code looks like.

Update: Part 3 is now available.

Somewhere between obsessive and sloppy lies a programmer’s coding style and methodologies. The real trick is to be able to spot a person who is dedicated to not just ‘writing code’ but building an application that will be maintainable for your company now and in the future. Code that is poorly structured and/or commented leads to excessive time-lost when transitioning from one programmer to another. Further, if your company is doing well and you bring on a new programmer, they may be just as upset at having to work with their co-worker’s poor efforts.

Coding Methodologies
Unless your company has a pre-defined programming methodologies list, your developer will do their usual, individual programming style. In PHP programming having organization is a key element to not only maintainable software but also helps to prevent code-waste. Many novice PHP programmers will do their work procedurally or with very little consideration to structured, function-oriented coding practices. For instance, a more novice programmer may create a web site with a block of code such as:

print "Categories:\n";
for ($i=0; $i<10; $i++) {
    print "Category: $i\n";
}

This code works and does the job. Now imagine that you want to use this same code for not just categories but 30 other sections of the site. A programmer concerned with maintainability would opt to build this into a function and be able to manipulate one function if they had to change this code rather than 30 separate blocks spread over as many files. Here's a simplistic function to handle that idea:

function printGroup($listName, $itemName, $total, $iterate) {
    print "$listName:\n";
    for ($i=0; $i<$total; $i=$i+$iterate) {
        print "$itemName: $i\n";
    }
}
printGroup("Categories", "Category", 10, 1);

Commenting Code
Quality code commenting is the one thing every programmer should do but rarely does. Comments are always seen as "that extra step" in the process that gets cut-out due to time restrictions or just apathy. As a business owner or manager you have a role in this part. Encourage your developers to comment and make them aware this is not only expected but required as part of their work. A fantastic way to get this process started is to suggest utilizing self-documenting comments such as phpDocumentor style comments. Here's a small example:

/**
 * forum.class.php - Forum Class
 * 
 * This class provides the required functions to build-out a simple
 * forum for usage through any web site that requires such functionality.
 * 
 * @author Mark Stanislav 
 * @copyright Copyright (c) 2010, MNX Solutions
 * @license http://opensource.org/licenses/gpl-license.php GNU GPL
 * @version 0.98
 * @package forum
 */

Commenting code not only makes understanding developer decisions and thoughts easier about why certain code was written the way it was, but also encourages developers to re-think their code. For instance, if a developer starts to write the description for a function, they may realize that this functionality had already been written about elsewhere and that they should merge functionality and remove code duplication.

Remember, code organization and commenting should be the standard, not a 'nice-to-have'. When looking for programmers or at their example code, ensure that they are structuring code with sensible function names, consistent style (indentation for example), and logical variable names. Ask your would-be developer how they tend to comment code and to give examples of standard programming frameworks they utilize to write maintainable code. A professional programmer should have no trouble explaining their examples and the thought that went behind each decision.

2 Responses to “Hiring a PHP Programmer: Part #2, Code Organization & Commenting”

  1. Lucas Mathews says:

    PHP is one of the usually used, typical purpose scripting ‘languages’ especially appropriate for web content management and can be placed along with HTML.

  2. Alden Kent says:

    A awesome way to get this process started is to suggest using self-documenting reviews such as phpDocumentor style reviews.

Leave a Reply