Estándares de codificación

Cuando aportes código a Symfony2, debes seguir sus estándares de codificación. Para no hacer el cuento largo, aquí está la regla de oro: limítate el código Symfony2 existente. La mayoría de los Paquetes de código abierto y librerías utilizadas por Symfony2 también siguen las mismas pautas, y también deberías hacerlo.

Recuerda que la principal ventaja de los estándares es que cada pieza de código se ve y se siente familiar, no se trata de que esta o esa sea más legible.

Symfony sigue los estándares definidos en los documentos PSR-0, PSR-1 y PSR-2.

Ya que una imagen —o algún código— vale más que mil palabras, he aquí un pequeño ejemplo que contiene la mayoría de las funciones descritas más adelante:

<?php

/*
 * This file is part of the Symfony package.
 *
 * (c) Fabien Potencier <fabien@symfony.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

namespace Acme;

/**
 * Demostración de estándares de la codificación.
 */
class FooBar
{
    const SOME_CONST = 42;

    private $fooBar;

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

    /**
     * @param string $dummy Some argument description
     * @param array $options
     *
     * @return string|null Transformed input
     */
    private function transformText($dummy, $options = array())
    {
        $mergedOptions = array_merge(
            $options,
            array(
                'some_default' => 'values',
                'another_default' => 'more values',
            )
        );

        if (true === $dummy) {
            return;
        }
        if ('string' === $dummy) {
            if ('values' === $mergedOptions['some_default']) {
                $dummy = substr($dummy, 0, 5);
            } else {
                $dummy = ucwords($dummy);
            }
        } else {
            throw new \RuntimeException(sprintf('Unrecognized dummy option "%s"', $dummy));
        }

        return $dummy;
    }
}

Estructura

• Añade un solo espacio después de cada delimitador coma;
• Añade un solo espacio alrededor de los operadores (==, &&, ...);
• Añade una coma después de cada elemento del arreglo en un arreglo multilínea, incluso después del último;
• Añade una línea en blanco antes de las declaraciones return, a menos que el valor devuelto solo sea dentro de un grupo de declaraciones (tal como una declaración if);
• Usa llaves para indicar la estructura del cuerpo de control, independientemente del número de declaraciones que contenga;
• Define una clase por archivo — esto no se aplica a las clases ayudante privadas, de las cuales no se tiene la intención de crear una instancia desde el exterior y por lo tanto no les preocupa la norma PSR-0;
• Declara las propiedades de clase antes que los métodos;
• Declare public methods first, then protected ones and finally private ones;
• Use parentheses when instantiating classes regardless of the number of arguments the constructor has;
• Exception message strings should be concatenated using sprintf.

Convenciones de nomenclatura

• Utiliza mayúsculas intercaladas —sin guiones bajos— en nombres de variable, función, método o argumentos;
• Usa guiones bajos para nombres de opción y nombres de parámetro;
• Utiliza espacios de nombres para todas las clases;
• Prefija las clases abstractas con Abstract. Por favor, ten en cuenta que algunas de las primeras clases de Symfony2 no siguen esta convención y no se han rebautizado por razones de compatibilidad hacia atrás. No obstante, todas las nuevas clases abstractas tienen que seguir esta convención de nomenclatura;
• Sufija las interfaces con Interface;
• Sufijo las características con Trait;
• Sufija las excepciones con Exception;
• Utiliza caracteres alfanuméricos y guiones bajos para los nombres de archivo;
• No olvides consultar el documento más detallado Convenciones para más consideraciones de nomenclatura subjetivas.

Documentación

• Añade bloques PHPDoc a todas las clases, métodos y funciones;
• Omite la etiqueta @return si el método no devuelve nada;
• Las anotaciones @package y @subpackage no se utilizan.

Licencia

• Symfony se distribuye bajo la licencia MIT, y el bloque de la licencia tiene que estar presente en la parte superior de todos los archivos PHP, antes del espacio de nombres.