Guía de estilo

Una guía de estilo es un conjunto de reglas para escribir código fuente de forma coherente y estandarizada.

Estas reglas permiten que todo los miembros del equipo de desarrollo puedan redactar código de forma semejante y puedan entenderse rápidamente.

¿Que son los PSR?

PSR es el acrónimo de PHP Standard recommendation, fue creado con el objetivo redactar reglas para escribir código fuente que pueda ser compartido y entendido por toda la comunidad de desarrolladores.

Estas recomendaciones son aceptadas y utilizadas ampliamente, proyectos como Symfony, Laravel, Composer o Magento siguen estas reglas y exigen el uso de estas reglas para poder contribuir con ellas.

Especificaciones PSR

Los PSR se han separado en varios documentos (estándar de código, interface de loggers, estándar de autoloading, interface de cache, etc), para nuestro caso sólo usaremos las recomendaciones de estándar de código.

PSR-1	Basic Coding Standard
PSR-2	Coding Style Guide

PSR-1: Basic Coding Standard

El PSR-1 contiene las recomendaciones básicas para escribir código estándar.

• Se deben utilizar únicamente las etiquetas <?php ?> y <?= ?>.
• Todos los archivos PHP deben utilizar la codificación UTF-8.
• Un archivo puede declarar símbolos (clases, funciones, constantes) o ejecutar la lógica de la aplicación (manipular datos, imprimir contenido), pero no ambos a la vez.
• Los namespaces y clases deben seguir el estándar PSR-4 (Cada clase debe estar en un archivo separado y debe un namespace).
• Los nombres de las clases deben estar en CamelCase empezando con mayúscula.
• Las constantes deben estar escritas en mayusculas y separados por un guión abajo _.
• Los nombres de los métodos deben estar en camelCase empezando con minúscula.

Ejemplo de uso

Supongamos que tenemos una clase para el perfil del usuario y que tiene dos métodos (para leer y asignar el nombre). Creamos la clase y la utilizamos:

<?php

class user_profile
{
    const version = '1.0';
    var $name = 'Guest';

    function GetName()
    {
        return $this->name;
    }

    function set_name($name)
    {
        $this->name = $name;
    }
}

$user = new user_profile();
echo 'Hello' . $user->GetName();

Este código funciona, pero habrán notado que no es fácil de leer pues los nombres de las clases y métodos no siguen un patrón para identificarlos rápidamente. Entonces usando las reglas del PSR-1, realizaremos los siguientes cambios:

• El nombre de la clase debe estar en CamelCase, es decir: UserProfile
• La constante debe estar en mayúsculas, es decir: VERSION
• El nombre del método debe estar en camelCase, es decir: getName
• El nombre del método debe estar en camelCase, es decir: setName
• Es necesario separar la declaración de la clase en otro archivo y utilizar un namespace.
• Es necesario usar un archivo separado para invocar la clase.

Con estos cambio ahora tendremos dos archivos, primero la definición de la clase:

<?php
// file: Kodetop/UserProfile.php

namespace Kodetop;

class UserProfile
{
    const VERSION = '1.0';
    var $name = 'Guest';

    function getName()
    {
        return $this->name;
    }

    function setName($name)
    {
        $this->name = $name;
    }
}

Seguido del archivo para utilizar la clase:

<?php

require 'Kodetop/UserProfile.php';

use Kodetop\UserProfile;

$user = new UserProfile();
echo 'Hello ' . $user->getName();

El resultado es código elegante, fácil de leer con lo que ahorraremos mucho tiempo al momento de darle mantenimiento y permitirá que otros desarrolladores lo entiendan rápidamente.

Referencias

• PHP Standard recommendation
• PHP_CodeSniffer