Guía de estilos de Symfony2

Posted by victor on March 6th, 2013
symfony2-logoLa guía de estilos de Symfony2 describe la forma de escribir el código de bundles y proyectos basados en Symfony framework para hacerlo más conciso y predecible. Esto toma mayor importancia cuando realizamos bundles que distribuimos a terceros o queremos contribuir a mejorar el núcleo del framework. Las convenciones seguidas por Symfony siguen los estándar PSR-0, PSR-1 y PSR-2 de PHP.

Convenciones de la estructura del código

  • Añade un espacio después de cada delimitador coma ','
    substr($dummy, 0, 5);
  • Añade un único espacio a ambos lados de un operador: =, ==, && etc...
    if($variable == true)
     $variable == true ? 'si' : 'no';
  • En los array multilínea, añade una coma al final de cada elemento, incluido el último:
    $array = Array(
        'elemento1' => 'valor1',
        'elemento2' => 'valor2', // coma final
    );
  • Añade un salto de línea antes de una sentencia return a menos que el return se encuentre solo en un bloque de sentencias, como por ejemplo if:
    class MiClase
    {
        public function miFuncion()
        {
            $salida = false;
                           // salto de línea
            return $salida;
        }
    }
    class MiClase
    {
        public function miFuncion()
        {
            $salida = false;
    
            if($salida == true)
            {
                return $salida; // Solo en un bloque de sentencias {...}
            }
    
            return $salida;
        }
    }
  • Usa las llaves para delimitar los bloques de código, con independencia del número de sentencias que contengan:
    // Correcto:
    if(true)
    {
        miFuncion();
    }
    
    // Mal:
    if(true)
        miFuncion();
  • Define una clase por archivo. Esto no tiene porque aplicarse a clases privadas auxiliares que solo se instancian desde una clase.
  • Las variables de una clase se declaran antes que los métodos.
  • Los métodos se declaran en el siguiente orden: public, protected y private.
  • Usa paréntesis al instanciar las clases, independientemente del número de argumentos:
    $a = new MiClase(); // Bien
    
    $a = new MiClase; // Mal

Convenciones de Nombres

  • El nombre de las clases se realiza en UpperCamelCase, es decir, que comienza por mayúscula.
  • Usa notación camelCase sin guiones bajos en variables, funciones, métodos y argumentos.
  • Usa el guión bajo para los nombres de opciones, y nombres de parámetros.
  • Todas las clases deben llevar namespace.
  • Las clases abstractas deben llevar el prefijo Abstract.
  • Las interfaces deben llevar el sufijo Interface.
  • Los traits (PHP >= 5.4) deben llevar el sufijo Trait.
  • Las excepciones deben tener el sufijo Exception.
  • Los nombres de fichero usan caracteres alfanuméricos y guiones bajos.

Documentación del código

  • Añade PHPDoc blocks a todas las clases, funciones y métodos.
  • No usar la etiqueta @return si un método no devuelve nada.
  • No se deben usar las siguientes etiquetas: @package y @subpackage.
 

Convenciones para el Core de Symfony2

Hasta ahora hemos descrito la guía de estilos para bundles y proyectos basados en Symfony2. A continuación, añadimos más convenciones para aquellos que se animen a colaborar con el desarrollo del framework: Para relacionar objetos existe una convención de nombres que nos facilita la comprensión de las relaciones. Cuando hay una relación 1:n, y esta relación se considera como principal se usan los siguientes nombres de métodos:
get()
set()
has()
all()
remove()
clear()
isEmpty()
add()
register()
count()
keys()
El concepto de "relación principal" puede ser un poco confuso y lo mejor es da un ejemplo: un contenedor de cookies tiene muchos objetos cookie. En la consola de Symfony2, podemos crear un comando que recibirá argumentos y opciones. El objeto input que recibe el método execute no es una "relación principal" por lo que no se le aplica la convención anterior.  Para todas aquellas relaciones que no encajen en el caso anterior se emplean la siguiente convención de nombres:
getXXX()
setXXX()  // Puede reemplazar o añadir un elemento.
replaceXXX() // No puede añadir un nuevo elemento. Si no existe genera excepción.
hasXXX()
getXXXs()
setXXXs() 
removeXXX()
clearXXX()
isEmptyXXX()
addXXX()
registerXXX()
countXXX()
  Documentación: Conding standards | Convenciones del núcleo de Symfony

Comments

comments powered by Disqus