As I slowly make my way back into personal coding projects and releasing OpenSource again I’ve decided to publish my Standards of Development.

Why?

Standards help keep code clean and consistent while adhering and enforcing to best practices and high quality. For most languages there is no required layout for code so below is the one I employ for most projects and languages.

Code Structures

When I write code most of my code structures follow the Allman style indention scheme with some slight modifications. Tthis is probably going to be the biggest upset as a lot of people prefer the K&R style variant 1TBS. This is probably as fundamental an argument as Vi and Emacs (I use nano – so there) the only difference is no one else is affected if you use Vi or Emacs – in source code though, hard shifts between 1TBS and Allman will cause quite a few eye soars. So it’s important before you start a project to agree on a standard for writing the code.

Here’s a basic code example

<?php
/**
 * This is a test file
 *
 * @author Marco Ceppi <marco@ceppi.net>
 * @package Example
 */

/**
 * Class Name
 *
 * It does STUFF
 *
 * @author Marco Ceppi <marco@ceppi.net>
 * @package Example
 * @subpackage if-required
 */
class Class_Name
{
	public $an_array = array();
	public $first_variable;
	public $second_variable;

	/**
	 * Class_Name Constructor
	 *
	 * @param string $param1
	 * @param string $param2
	 *
	 * @return void
	 */
	public function __construct( $param1, $param2 = 'default' )
	{
		$this->an_array = array('first' => 2, 'second');
	}

	/**
	 * Do Something
	 *
	 * Additional details about what this actually does
	 *
	 * @param string $param1
	 *
	 * @return mixed Details about what is returned
	 */
	public function do_something( $param1 = NULL )
	{
		return $this->_processThat($param1, $this->first_variable);
	}

	/**
	 * Process That
	 *
	 * Additional details about what this actually does
	 *
	 * @param string $param1
	 *
	 * @return mixed Details about what is returned
	 */
	private function _processThat( $param1, $param2 )
	{
		// Do something!
		if( $is_this )
		{
			// Do that
		}
		else if( !$is_other_thing )
		{
			// Doing this
		}
		else
		{
			// Gave up?
		}

		return $results;
	}
}

A quick break down.

Documentation

Each method, the file, and the class is documented using phpDoc format. If you’ve used Oracle’s javaDoc or any similar document templating system then most of the Syntax will be familiar. If you’ve never really documented code before consider this a wake up call.

Naming

Naming schemes are as equally important when writing code. Using a set standard continues readability of code. When creating names for methods, functions, classes, and variables the names should be as short while descriptive as possible. If a variable can not reasonably be named in less than ~15 characters it should be abbreviated as best as possible and a comment left above it’s first occurrence in the page detailing what it’s full name should be.

Formatting

While most projects typically go with either CamelCase, pascalCase, or under_score I’ve found a combination of the three to be effective in typecasting methods and variables. For starters class names are always first letter capitalized with underscores replacing spaces.

class User_Session {}

class User {}

Variables are all lowercase with _ replacing blank spaces

$username;
$post_id;
$multiple_worded_variable;

When naming functions and public class methods the same format for naming variables should take place.

function process_request( $req ) {}

class Generic
{
	public function start() {}

	/**
	 * Prepare Database Hook
	 */
	public function prepare_db_hook() {}
}

Finally the special cases which operate outside of the norm – Private and Protected scopes. I always treat these special when writing classes and objects. The shift from a normal naming scheme allows me to easily identify that they have a special ruleset applied to them – typically this naming scheme follows a _pascalCase format while adhering to the “15ish character” rule.

class Generic
{
	protected $_variableName;

	private function _secret() {}

	protected function _getDetails() {}

	private function _setUpdateRules() {}
}

Control Structures

Whether it’s an if, elseif, for, foreach, while, or switch the same general Allman style indentation applies. Parenthesis should be attached to the control structure and a blank white space should pad the open and close parenthesis at the first level. Further embedded parenthesis should hug their contents.

If, Else If, While, Foreach

These follow near the same formatting in regards to parameter acceptance.

if( !$is_active ) {}

if( ($user_id > 20 && $is_new) || !$is_active ) {}

while( $true === true ) {}

foreach( $array as $key => $val ) {}

Switch

With a switch each case starts and finishes on it’s own line on the same level. The default case should always be included regardless of use and should always be terminated with a break

switch( $mode )
{
	case 'first':
		// Contents
	break;
	default:
		// Fall back
	break;
}

For

The for loop should follow the same constraints as the above control structures, however I wanted to take a minute to highlight a best practice when creating loops.

Most for loops are iterating over an Array and performing various computations against it. What I see a lot, and want to stress is not best, is placement of the objects count in the evaluation portion of the loop. For loops are structured by for( LOOP START; EACH TIME; END OF EARCH RUN ) having a count executed each time the loop completes adds execution time to the script. Instead prepare everything in the loop start.

$roommate_names = array('Jim', 'Marco', 'Sara');

for( $i = 0, $total = count($roommate_names); $i < $total; $i++ ) {}

Or just perform the count outside of the loop. Typically I avoid for loops at all cost deferring to its cousin foreach unless there is no other possible solution.

This is a living document last updated 2011-04-05 4:00PM EDT