Since a community development imply multiple developpers, the Spiral project defines some coding conventions that make people write better code and everybody well understand. These are the first steps of a good code quality.

We've tried to define only few important conventions, since too many rules would not be respected at all.

Please try to conform on these rules when coding for Spiral.

Note: We encourage you to read and base on the existing code of Spiral, which is another way to learn the coding conventions.

All from documentation articles to code comments and variable names must be in English (the most common language for everybody on this planet!)

Errors and warnings should be set as E_ALL | E_STRICT during developpement phase.

No register_globals.

Use <?php tag instead of <? tag.

Files that contains only PHP code should not be ended by the ?> PHP close tag.

Folder names are in lower case to match with namespaces.

Folders are organized this way:

\				<- Spiral root directory
	\projectname
		\package

Each package folder is organized like this:

\classes
	\subpackage
		\subsubpackage
\configuration
\documentation
\meta
\resources
\tests

Only one class definition per file.

The file has the same name as the class. For example the file name for class MyClassName will be MyClassName.php.

Files are encoded in UTF-8.

We use tabulations, not spaces.

Tabulation size is usually 4, but it's up to you.

We always use brackets (”{” and ”}”), even for single line “if” statements.

Brackets should also be opened on a new line.

if($foo == $bar)
{
	// Your code here
}

class MyClass
{
	// Your code here
}

Avoid using short syntax if like:

echo 'I feel ' . ($good ? 'good' : 'right') . '!';

Prefer using single quote ' than double ” for strings. It has been proven that single quotes are quite faster.

Namespaces, have to be in lower case.

All classes in Spiral must belong to a namespace.

The convention for namespaces name is :

\spiral\projectname\package\subpackages

The project name is for example framework.

The package name is a package of the project for example persistence.

Subpackages are up to the developpers.

Use the “use” keyword to specify dependencies on a class outside of the current namespace. Each class or interface dependency must be explicitly declared by a “use” if the dependency is outside of the current namespace. Then use the class name in your code.

Classes or interfaces that are declared by “use” or that belong to the current namespace, can be refered directly without using the complete namespaced name.

If two classes (or interfaces) have the same name (in different namespaces), you should use the whole namespaced name of classes that are outside of the current namespace.

Do not use the aliasing feature of the “use” keyword. This often brings ambiguity.

Do not use require_once, the Spiral autoload will do it for you.

Classes and interfaces names respect the UpperCamelCase notation.

A class should always implement an interface. This makes extension much easier.

Class names should end with the name of the interface implemented.

interface ObjectRepository
{
}

class ORMObjectRepository implements ObjectRepository
{
}

Methods and attributes respect the lowerCamelCase notation.

Private or protected methods/attributes should be prefixed by an underscore “_”.

Methods parameters that can be explicitly casted should be explicitly casted! Parameters that can be casted are objects which type (interface) is known or arrays.

function myMethod(ObjectType $param1, array $param2)
{
}

Constants are in uppercase, spaces converted in underscores: “MY_CONST” is a constant.

Generally speaking, no constant should be made global. All constants should belong to a class.

Even if no comments are given here, you do have to comment your code!

class ImplementationOfMyClass implements MyClass
{
	const MY_CONST = 1;
 
	private $_privateAttribute;
 
	public $publicAttribute;
 
	public function __construct()
	{
		// code
	}
 
	protected function _protectedMethod()
	{
		// code
	}
 
	public function publicMethod()
	{
		// code
	}
}

Comments respect the PHPDoc convention which is quite the same as JavaDoc.

Some principles of good comments :

1. You should systematically comment your code
2. Think that people who are reading the documentation don't know what happens in your brain!
3. Don't be afraid of being verbose and repeating yourself
4. Try to make links between elements. For example, the doc block that describes the ObjectRepository interface, should make a link to the Query interface.
5. Write some examples on the way your code should be used well.

/**
 * Short description
 *
 * Long description (not required)
 * 
 * @author	James Brown <james@spiral-project.org>
 * @copyright	2009 Spiral-project.org <http://www.spiral-project.org>
 * @license	GNU General Public License <http://www.gnu.org/licenses/gpl.html>
 */

/**
 * Short description
 *
 * Long description (not required)
 * 
 * @param	string		$param		Description of param
 * @param	ObjectType	$param2		Description of param 2
 * @return  	array		Description of returned value
 * @throws  	Exception	Description of the potential throwed exception
 */

/**
 * Short description
 *
 * Long description (not required)
 * 
 * @var	string
 */