propelorm/Propel2 — Issue #2: Propel2 Coding Standards
Author: willdurand
Created: 2011-10-14 07:02:21+00:00
State: open

# Propel2 Coding Standards #

We use the Symfony2 convention, here is a short example (from http://symfony.com/doc/current/contributing/code/standards.html):

``` php
foo = $this->transform($dummy);
}

/**
* @param string $dummy Some argument description
* @return string|null Transformed input
*/
private function transform($dummy)
{
if (true === $dummy) {
return;
} elseif ('string' === $dummy) {
$dummy = substr($dummy, 0, 5);
}

return $dummy;
}
}
```

Structure
------------

* Never use short tags (`` closing tag;
* Indentation is done by tabs (**WARNING: for now it differs from Symfony2 CS - To discuss**);
* Use the linefeed character (`0x0A`) to end lines;
* Add a single space after each comma delimiter;
* Don't put spaces after an opening parenthesis and before a closing one;
* Add a single space around operators (`==`, `&&`, ...);
* Add a single space before the opening parenthesis of a control keyword (`if`, `else`, `for`, `while`, ...);
* Add a blank line before return statements, unless the return is alone inside a statement-group (like an if statement);
* Don't add trailing spaces at the end of lines;
* Use braces to indicate control structure body regardless of the number of statements it contains;
* Put braces on their own line for classes, methods, and functions declaration;
* Separate the conditional statements (`if`, `else`, ...) and the opening brace with a single space and no blank line;
* Declare visibility explicitly for class, methods, and properties (usage of `var` is prohibited);
* Use lowercase PHP native typed constants: `false`, `true`, and `null`. The same goes for `array()`;
* Use uppercase strings for constants with words separated with underscores;
* Define one class per file;
* Declare class properties before methods;
* Declare public methods first, then protected ones and finally private ones;
* Organize `use` alphabetically.

## Naming Conventions ##

* Use camelCase, not underscores, for variable, function and method names;
* Use underscores for option, argument, parameter names;
* Use namespaces for all classes;
* Use Symfony as the first namespace level;
* Suffix interfaces with Interface;
* Use alphanumeric characters and underscores for file names;
* Don't forget to look at the more verbose Conventions document for more subjective naming considerations.

## Documentation ##

* Add PHPDoc blocks for all classes, methods, and functions;
* Omit the `@return` tag if the method does not return anything;
* The `@package` and `@subpackage` annotations are no more used.

## License ##

The following license has to be included in all files:

```
/**
* This file is part of the Propel package.
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*
* @license MIT License
*/
```