Coding Standards

harikt edited this page Aug 26, 2012 · 2 revisions
Clone this wiki locally

Propel2 Coding Standards

We use the PSR-0, PSR-1, PSR-2 convention of php-fig

<?php

/**
 * 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
 */

namespace Propel;

use A\Baz;
use B\Bar;

class Foo
{
    const SOME_CONST = 42;

    private $foo;

    /**
     * @param string $dummy Some argument description
     */
    public function __construct($dummy)
    {
        $this->foo = $this->transform($dummy);
    }

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

        return $dummy;
    }
}

Structure

  • Don't end class files with the usual ?> closing tag;
  • Indentation is done by 4 spaces, don't use tabs;
  • All PHP files MUST use the Unix LF (linefeed) line ending.
  • All PHP files MUST end with a single blank line.
  • 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 class visibility after static or final keywords (e.g. final public, static public, final static, ...);
  • Organize use alphabetically and group them by Runtime, Generator, and others. Each group will be separated by a new blank line.

Naming Conventions

  • Use camelCase, not underscores, for variable, function and method names;
  • Use namespaces for all classes;
  • Use Propel 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
 */