Guía de estilo

Introducción

Una guía de estilo de un lenguaje de programación es un conjunto de recomendaciones sobre la forma de dar formato a los programas. El interés de utilizar un estilo específico es facilitar la reutilización de código y la detección de errores. Existen muchos estilos de programación y no se puede decir que uno sea mejor que otro, pero sí que es conveniente adoptar algún estilo determinado y utilizarlo de forma consistente.

El estilo utilizado en estos apuntes y que se recomienda sigan los alumnos se basa:

• En primer lugar, en la guía de estilo PSR-2 del grupo PHP-FIG (PHP Framework Interop Group), un grupo en el que participan los autores de los frameworks PHP más populares,
• En segundo lugar, en la guía de estilo oficial del proyecto PEAR, el proyecto más importante de bibliotecas para PHP,
• En tercer lugar, en las preferencias personales del autor.

Nota: Existe una guía de estilo oficial de PHP, pero esta guía se refiere al código fuente de PHP, que está escrito en C, y está dirigida a los programadores que desarrollan el lenguaje, no se refiere a programas escritos en PHP.

En esta lección se comentan las recomendaciones de estilo más importantes. Cuando las reglas de estilo ...

• Provienen de PSR-2 y PEAR, las reglas de estilo utilizan las expresiones "se debe ..." o "no se debe ...".
• Provienen de PSR-2 o PEAR, se indica entre corchetes el nombre de la guía.
• son elecciones del profesor se utilizan las expresiones "se aconseja ..." o "no es necesario ...".

Guía de estilo

Configuración de php

[PEAR] El código no debe generar errores o avisos cuando la directiva error_reporting tiene el valor E_STRICT.

Delimitadores de bloque PHP

Los framentos PHP deben delimitarse con <?php ... ?> y no con <? ... ?>.

<?php
print "<p>Hola</p>";
?>

[PSR-2] También puede utilizarse <?= ... ?>.

<?= "<p>Hola</p>" ?>

Comentarios

Se aconseja utilizar \/\/ en los comentarios de una sola línea.

Los comentarios de varias líneas pueden delimitarse con \/* ... *\/ o con varios \/\/.

No se debe utilizar #.

Para facilitar la legibilidad, se aconseja colocar el cierre del comentario de varias líneas (*\/) al principio de la línea (aunque puede ir precedido por espacios en blanco).

<?php
$nombre = "Fulano" // Nombre del individuo
?>

<?php
/* Datos personales:
   Nombre, apellidos
*/
$nombre    = "Fulano"
$apellidos = "Mengánez Zutánez";
?>

<?php
// Datos personales:
// Nombre, apellidos
$nombre    = "Fulano"
$apellidos = "Mengánez Zutánez";
?>

Bloques de comentario iniciales

[PEAR] Los programas deben incluir al principio del documento bloques de comentarios (docblocks).

<?php
/**
* Descripción breve
*
* Descripción extensa (opcional)
*
* @author Fulanito de Tal <[email protected]>
* @copyright 2007 Fulanito de Tal
* @license http://www.fsf.org/licensing/licenses/gpl.txt GPL 2 or later
* @version 2007-02-06
* @link http://www.example.org
*/
?>

Por completar: mencionar JavaDoc y phpDocumentor.

Longitud de línea

No se deben superar los 85 caracteres por línea.

Al partir una línea, la segunda y siguientes líneas deben sangrarse 4 espacios. Si es posible, estas líneas deben empezar por un operador.

<?php
print "<p>Este texto es muy largo y no cabe en una sola línea, así que he "
    . "partido el texto en dos líneas escribiendo el operador de concatenación "
    . "(.) al principio de cada línea.</p>";
?>

Instrucciones por línea

Se aconseja no incluir más de una instrucción por línea.

Espacios en blanco

[PEAR] Después de una coma, debe haber un espacio en blanco.

<?php
$var = foo($bar, $cel, $ona);
?>

[PEAR] Cualquier operador binario (por ejemplo: + - * \/ = . == && || ? : ) debe estar rodeado de espacios en blanco.

<?php
$cmTotal = 100000 * $km + 100 * $m + $cm;
?>

[PEAR] Los operadores unarios (por ejemplo: ! ++ --) deben unirse a su argumento sin espacios en blanco.

<?php
$correcto = !$error;
?>

Líneas en blanco

Se aconseja separar con líneas en blanco las diferentes partes de un programa (recogida de datos, mensajes de error, respuesta del programa, etc.).

Comillas dobles y simples

Se aconseja delimitar las cadenas con comillas dobles (") en vez de con comillas simples ('). Se aconseja también que el código html generado por PHP incluya comillas dobles:

<?php
print "<p style="text-align: center">Hola</p>";
?>

Nombres de variables

[PEAR] Los nombres de variables deben escribirse con el estilo camelCase, es decir empezar en minúscula y, si el nombre de la variable está formada por varias palabras, la primera letra de las palabras (menos la primera) debe escribirse en mayúscula.

$nombre         = "Fulano";
$nombreAlumno   = "Mengano";
$nombreProfesor = "Zutano";

Alineación de definiciones de variables

[PEAR] Si se definen varias variables, se deben alinear las igualdades con espacios en blanco para facilitar la legibilidad.

$nombre         = "Fulano";
$nombreAlumno   = "Mengano";
$nombreProfesor = "Zutano";

Nota: Este estilo está recomendado en la guía de estilo de PEAR y desaconsejado en la guía de estilo de Python.

Constantes

Las constantes deben escribirse en mayúsculas y separando las palabras con guiones bajos (_).

Las constantes true, false y null debe escribirse en minúsculas.

Sangrado

Se debe utilizar un sangrado de 4 espacios y no utilizar tabuladores. En estructuras anidadas, se acumularán los sangrados.

<?php
if (condicion1) {
    accion1;
} else {
    accion2;
    if (condicion3) {
        accion3;
    } else {
        accion4;
    }
}
?>

Estructuras de control

Las estructuras de control deben tener un espacio entre la palabra reservada y el paréntesis inicial, para distinguirlas de las funciones.

En los bloques de sentencias deben utilizarse siempre llaves, incluso cuando podrían omitirse (por ejemplo, cuando el bloque está formado por una única sentencia). La llave de apertura debe situarse al final de la línea y la llave de cierre debe situarse al principio de la línea.

Ejemplos de estructuras de control:

<?php
if (condicion1 || condicion2) {
    accion1;
} elseif (condicion3 && condicion4) {
    accion2;
} else {
    accionpredeterminada;
}
?>

for (expresión_inicial; expresión_final; expresión_paso) {
    bloque_de_sentencias
}

foreach ($matriz as $valor) {
    bloque_de_sentencias
}

while (expresión) {
    bloque_de_sentencias
}

do {
    bloque_de_sentencias
} while (expresión)

<?php
switch (condicion) {
case 1:
    accion1;
    break;

case 2:
    accion2;
    break;

default:
    accionpredeterminada;
    break;
}
?>

Expresiones lógicas

No es necesario comparar las variables booleanas con los valores true o false, se aconseja utilizar directamente la variable o su negación.

En vez de:

if ($correcto == true) {
    print "<p>Es correcto</p>";
}
if ($correcto == false) {
   print "<p>No es correcto</p>";
}

se aconseja escribir:

if ($correcto) {
    print "<p>Es correcto</p>";
}
if (!$correcto) {
   print "<p>No es correcto</p>";
}

Al concatenar expresiones lógicas sencillas, no es necesario escribir cada expresión entre paréntesis.

if ($numero < 0 || $numero > 100) {
    print "<p>El número no está en el intervalo [0, 100]</p>";
}

Definición de funciones

[PEAR] Las funciones deben declararse de acuerdo con el estilo "BSD Allman":

<?php
function fooFuncion($arg1, $arg2 = '')
{
    if (condicion) {
        sentencia;
    }
    return $val;
}
?>

Los argumentos con valores predeterminados se deben colocar al final de la lista de argumentos.

Las funciones deben devolver algún valor.

Llamadas a funciones

No debe haber espacios entre el nombre de la función, el paréntesis inicial y el primer argumento. Debe haber espacios tras las comas que separen argumentos. No debe haber espacios entre el último argumento, el paréntesis final y el punto y coma.

<?php
$var = foo($bar, $cel, $ona);
?>

Bibliotecas

[PEAR] Para incluir bibliotecas cuya inclusión no depende de ninguna condición, debe utilizarse require_once y no deben utilizarse paréntesis alrededor del nombre de la biblioteca.

require_once "biblioteca.php";
 ...

Gestión de errores

Por completar.

Herramientas

PHP-Beatifier es un paquete PEAR que formatea automáticamente archivos PHP.

PHP_CodeSniffer es un paquete PEAR que detecta errores de formateo en archivos PHP.

phpDocumentor es un paquete PEAR que detecta errores de formateo en archivos PHP.