Estándares de codificación¶

Añadir nuevas funcionalidades¶

Las nuevas funcionalidades no se deberán añadir sin sus propias pruebas, las cuales deberán ser superadas antes de hacer el commit en el repositorio.

Configuración del IDE¶

Asegúrate de que tu IDE haga trim por la derecha para que no haya espacios al final de las líneas.

La mayoría de los IDE modernos soportan archivos .editorconfig. El esqueleto de aplicación de CakePHP viene con él por defecto y contiene las mejores prácticas de forma predeterminada.

Tabulación¶

Se utilizará cuatro espacios para la tabulación.

Por lo que debería everse asi:

// nivel base
    // nivel 1
        // nivel 2
    // nivel 1
// nivel base

O también:

$booleanVariable = true;
$stringVariable = 'moose';
if ($booleanVariable) {
    echo 'Boolean value is true';
    if ($stringVariable === 'moose') {
        echo 'We have encountered a moose';
    }
}

En los casos donde utilices llamadas de funciones que ocupen más de una línea usa las siguientes guías:

• El paréntesis de abertura de la llamada de la función deberá ser lo último que contenga la línea.

• Sólo se permite un argumento por línea.

• Los paréntesis de cierre deben estar solos y en una línea por separado.

Por ejemplo, en vez de utilizar el siguiente formato:

$matches = array_intersect_key($this->_listeners,
                array_flip(preg_grep($matchPattern,
                    array_keys($this->_listeners), 0)));

Utiliza éste en su lugar:

$matches = array_intersect_key(
    $this->_listeners,
    array_flip(
        preg_grep($matchPattern, array_keys($this->_listeners), 0)
    )
);

Tamaño de línea¶

Es recomendable mantener un tamaño de 100 caracteres por línea para una mejor lectura del código y tratar de no pasarse de los 120.

En resumen:

• 100 caracteres es el límite recomendado.

• 120 caracteres es el límite máximo.

Estructuras de control¶

Las estructuras de control son por ejemplo «if», «for», «foreach», «while», «switch» etc. A continuación un ejemplo con «if»:

if ((expr_1) || (expr_2)) {
    // accion_1;
} elseif (!(expr_3) && (expr_4)) {
    // accion_2;
} else {
    // accion_por_defecto;
}

• En las estructuras de control deberá haber un espacio antes del primer paréntesis y otro entre el último y la llave de apertura.

• Utiliza siempre las llaves en las estructuras de control incluso si no son necesarias. Aumentan la legibilidad del código y te proporcionan menos errores lógicos.

• Las llaves de apertura deberán estar en la misma línea que la estructura de control, las de cierre en líneas nuevas y el código dentro de las dos llaves en un nuevo nivel de tabulación.

• No deberán usarse las asignaciones inline en las estructras de control.

// Incorrecto: sin llaves y declaración mal posicionada
if (expr) statement;

// Incorrecto: sin llaves
if (expr)
    statement;

// Correcto
if (expr) {
    statement;
}

// Incorrecto = asignación inline
if ($variable = Class::function()) {
    statement;
}

// Correcto
$variable = Class::function();
if ($variable) {
    statement;
}

// Correcto, sencillo y legible
$variable = isset($options['variable']) ? $options['variable'] : true;

// Incorrecto, operadores anidados
$variable = isset($options['variable']) ? isset($options['othervar']) ? true : false : false;

<?php
if ($esAdmin):
    echo '<p>Eres el usuario admin.</p>';
endif;
?>
<p>Lo siguiente es aceptado también:</p>
<?php if ($esAdmin): ?>
    <p>Eres el usuario admin.</p>
<?php endif; ?>

Comparación¶

Intenta ser siempre lo más estricto posible. Si una comparación no es estricta de forma deliberada, puede ser inteligente añadir un comentario para evitar confundirla con un error.

Para comprobar si una variable es null se recomienda utilizar la comprobación estricta:

if ($value === null) {
    // ...
}

El valor contra el que se va a realizar la comparación deberá ir en el lado derecho de esta:

// no recomendado
if (null === $this->foo()) {
    // ...
}

// recomendado
if ($this->foo() === null) {
    // ...
}

Llamadas de funciones¶

Las llamadas a funciones deben realizarse sin espacios entre el nombre de la función y el parentesis de apertura y entre cada parámetro de la llamada deberá haber un espacio:

$var = foo($bar, $bar2, $bar3);

Como puedes ver arriba también deberá haber un espacio a ambos lados de los signos de igual.

Definición de métodos¶

Ejemplo de definición de un método:

public function someFunction($arg1, $arg2 = '')
{
    if (expr) {
        statement;
    }

    return $var;
}

Parámetros con un valor por defecto deberán ir al final de las definiciones. Trata que tus funciones devuelvan siempre un resultado, al menos true o false, para que se pueda determinar cuando la llamada a la función ha sido correcta:

public function connection($dns, $persistent = false)
{
    if (is_array($dns)) {
        $dnsInfo = $dns;
    } else {
        $dnsInfo = BD::parseDNS($dns);
    }

    if (!($dnsInfo) || !($dnsInfo['phpType'])) {
        return $this->addError();
    }

    return true;
}

Como puedes ver hay un espacio a ambos lados del signo de igual.

/**
 * Alguna descripción del método
 *
 * @param \Cake\ORM\Table $table La clase table a utilizar.
 * @param array $array Algún valor array.
 * @param callable $callback Algún callback.
 * @param bool $boolean Algún valor boolean.
 */
public function foo(Table $table, array $array, callable $callback, $boolean)
{
}

/**
 * Alguna descripción del método.
 *
 * @param array|\ArrayObject $array Algún valor array.
 */
public function foo($array)
{
}

$closure = function ($arg1, $arg2) use ($var1, $var2) {
    // código
};

Encadenación de métodos¶

Las encadenaciones de métodos deberán distribuir estos en líneas separadas y tabulados con cuatro espacios:

$email->from('[email protected]')
    ->to('[email protected]')
    ->subject('A great message')
    ->send();

Comentar el código¶

Todos los comentarios deberán ir escritos en inglés y describir de un modo claro el bloque de código comentado.

Los comentarios pueden incluir las siguientes etiquetas de phpDocumentor:

• @deprecated Usando el formato @version <vector> <description>, donde version y description son obligatorios.

• @example

• @ignore

• @internal

• @link

• @see

• @since

• @version

Las etiquetas PhpDoc son muy similares a las etiquetas JavaDoc en Java. Las etiquetas solo son procesadas si son el primer elemento en una línea DocBlock, por ejemplo:

/**
 * Ejemplo de etiqueta.
 *
 * @author esta etiqueta es parseada, pero esta @version es ignorada
 * @version 1.0 esta etiqueta es parseada también
 */

/**
 * Ejemplo de etiquetas phpDoc inline.
 *
 * Esta función trabaja duramente con foo() para manejar el mundo.
 *
 * @return void
 */
function bar()
{
}

/**
 * Función foo.
 *
 * @return void
 */
function foo()
{
}

Los bloques de comentarios, con la excepción del primer bloque en un archivo, deberán ir siempre precedidos por un salto de línea.

int|bool

/**
 * Función foo.
 *
 * @return $this
 */
public function foo()
{
    return $this;
}

Incluir archivos¶

include, require, include_once y require_once no tienen paréntesis:

// mal = paréntesis
require_once('ClassFileName.php');
require_once ($class);

// bien = sin paréntesis
require_once 'ClassFileName.php';
require_once $class;

Cuando se incluyan archivos con clases o librerías usa siempre y únicamente la función require_once.

Etiquetas PHP¶

Utiliza siempre las etiquetas <?php y ?> en lugar de <? y ?>.

La sintaxis abreviada de echo deberá usarse en los archivos de plantilla (.php) donde proceda.

// mal = con punto y coma y sin espacios
<td><?=$name;?></td>

// bien = con espacios y sin punto y coma
<td><?= $name ?></td>

Convenciones de nomenclatura¶

function nombreFuncionLargo()
{
}

class ClaseEjemplo
{
}

$usuario = 'John';
$usuarios = ['John', 'Hans', 'Arne'];

$dispatcher = new Dispatcher();

nombre_de_archivo_largo.php

define('CONSTANTE', 1);

define('NOMBRE_DE_CONSTANTE_LARGO', 2);

Cuidado al usar empty()/isset()¶

Aunque empty() es una función sencilla de utilizar, puede enmascarar errores y causar efectos accidentales cuando se usa con '0' y 0. Cuando las variables o propiedades están ya definidas el uso de empty() no es recomendable. Al trabajar con variables es mejor utilizar la conversión a tipo booleano en lugar de empty():

function manipulate($var)
{
    // No recomendado, $var está definido en el ámbito
    if (empty($var)) {
        // ...
    }

    // Utiliza la conversión a booleano
    if (!$var) {
        // ...
    }
    if ($var) {
        // ...
    }
}

Cuando trates con propiedades definidas deberías favorecer las comprobaciones sobre null en lugar de empty()/isset():

class Thing
{
    private $property; // Definido

    public function readProperty()
    {
        // No recomendado al estar definida la propiedad en la clase
        if (!isset($this->property)) {
            // ...
        }
        // Recomendado
        if ($this->property === null) {

        }
    }
}

Cuando se trabaja con arrays, es mejor hacer merge de valores por defecto en vez de hacer comprobaciones con empty(). Haciendo merge de valores por defecto puedes asegurarte de que las claves necesarias están definidas:

function doWork(array $array)
{
    // Hacer merge de valor por defecto para eliminar la necesidad
    // de comprobaciones empty
    $array += [
        'key' => null,
    ];

    // No recomendado, la clave ya está seteada
    if (isset($array['key'])) {
        // ...
    }

    // Recomendado
    if ($array['key'] !== null) {
        // ...
    }
}