Alcance Libre - :: Guía de Códificación para PHP

::Guía de Códificación para PHP

Autor: Pablo Rene Monroy Sánchez
Correo electrónico: correo arroba pablomonroy punto com punto mx
Sitio de Red: http://www.pablomonroy.com.mx/
Jabber ID: pablomonroy@jabber.org
Creative Commons

Reconocimiento-NoComercial-CompartirIgual 2.5

© 2006 Pablo Monroy. Usted es libre de copiar, distribuir y comunicar públicamente la obra y hacer obras derivadas bajo las condiciones siguientes: a) Debe reconocer y citar al autor original. b) No puede utilizar esta obra para fines comerciales. c) Si altera o transforma esta obra o genera una obra derivada, sólo puede distribuir la obra generada bajo una licencia idéntica a ésta. Al reutilizar o distribuir la obra, tiene que dejar bien claro los términos de la licencia de esta obra. Alguna de estas condiciones puede no aplicarse si se obtiene el permiso del titular de los derechos de autor. Los derechos derivados de usos legítimos u otras limitaciones no se ven afectados por lo anterior. Licencia completa en castellano. La información contenida en este documento y los derivados de éste se proporcionan tal cual son y los autores no asumirán responsabilidad alguna si el usuario o lector hace mal uso de éstos.

SQL

Las sentencias SQL dentro de php deberán estar en siempre en minúsculas y en líneas múltiples

Ejemplo:

<?php
$sql= "
select
ClienteID
,ClienteNombre
,ClienteDireccion
from
Clientes
where
ClienteID = $cliente_id"
?>

Nombres

Nombres de Variables

$minusculas_con_guion_bajo

Nombres de Propiedades

$minusculas_con_guion_bajo

Nombres de Métodos

minusculasMayuscula()

Nombres de Función

$minusculas_con_guion_bajo()

Ejemplos:

<?php
// incorrecto: espacios junto a los paréntesis
obtener_datos_usuario( $usuario, $password );

// incorrecto: sin espacios entre argumentos
obtener_datos_usuario($usuario,$password);

// ambiguo: ¿Qué almacenan las variables $a y $b?
obtener_datos_usuario($a, $b);

// correcto
obtener_datos_usuario($usuario, $password);
?>

Nombres de Clases

MayusculasMinusculas

Nombres de constantes

MAYUSCULAS_CON_GUION_BAJO

Inclusión de Archivos

Cuando se incluyan otros archivos en nuestro código usando require_once y include_once ya que estas no son propiamente llamadas a funciones no es necesario usar los paréntesis.

Ejemplos:

<?php
require_once 'Cliente.php';
include_once 'OdenDeTrabajo.php';
?>

Indentación y Espacios

Se recomienda que la longitud de las líneas en archivos sean de un máximo de 80 caracteres.

Se recomienda que ningún bloque del código -sin separación de líneas en blanco- sea más largo que una sola pantalla (aproximadamente ~30 líneas). La limitación de la longitud de los bloques del código hace más fácil la lectura del código.

Cuando en una sola línea se escriben varias sentencias, para efecto de una mejor lectura puede partirse en varias líneas para una mejor lectura.

Ejemplo:

<?php
$nombre_de_variable_largo =
$this->algunMetodo('prueba') +
ALGUNA_CONSTANTE;

if ($mi_variable + 12 > $max ||
$default === null)
{
...
}
?>

Si tiene varias sentencias escritas una tras otra, puede hacer espacios para que alinear su código y sea más entendible.

<?php
$this->id = 0;
$this->nombrecorto = 'prueba';
$this->titulo = 'Prueba Articulo';
?>

También es recomendable dejar un espacio en blanco entre operadores para un mejor entendimiento de las sentencias. Una excepción es el "." que sirve como concatenador, además del ";" del final de cada línea.

Ejemplo:

<?php
$mi_variable = $otra_variable + 1;
echo 'esto es una prueba '.$mi_variable;
?>

Es recomendable la longitud del tabulador y de la indentación en su editor sea establecida en 4 espacios.

Llaves

La llaves siempre debe de ser incluidas cuando usamos las sentencias if, for, while etc. No hay excepciones a esta regla.

Ejemplo de usos incorrectos/correctos usando llaves:

<?php
/* Las siguientes son incorrectas */
if ( condition ) foo();

if ( condition )
foo();

while ( condition )
foo();

for ( $i = 0; $i < 10; $i++ )
foo($i);

/* Las siguientes son correctas */
if ( condition )
{
foo();
}

while ( condition )
{
foo();
}

for ( $i = 0; $i < 10; $i++ )
{
foo($i);
}
?>

Debe tomarse el siguiente ejemplo para el uso de llaves

<?php
if ( condition )
{
while ( condition )
{
foo();
}
}
?>

Estuturas de Control

Esto incluye las instrucciones if, for, while, switch, etc.

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

Para la sentencia switch :

<?php
switch (condicion) {
case 1: {
accion1;
break;
}
case 2: {
accion2;
break;
}
default: {
defaultaccion;
break;
}
}
?>

Clases

Para nombrar clases ver , para documentar la clase ver

Definir siempre si los métodos y propiedades son: public, protected, private

Ejemplo:

<?php
class ClasePrueba
{
public $id = null;

protected $children = array();

private $counter = 0;

public function __construct($id)
{
$this->id = $id;
}

public function display()
{
// mostar prueba clasetest class ...
$this->displayChildern();
}

protected displayChildren()
{
// mostar children ...
}

private incrementCounter()
{
$this->counter++;
}
}

?>

Documentación

Todas las clases, métodos, funciones y características requieren docblocks. Docblocks es analizado por phpDocumenter que genera automáticamente la documentación.

Las reglas para Docblocks son las siguientes

La primera línea es un resumen corto que comienza con una mayúscula y que no se debe de terminar con un punto.
Después del resumen está una línea en blanco.
La línea siguiente es una descripción larga multilínea y puede llevar puntuación.
Después de esta descripción está una línea en blanco.
Etiquetas requeridas, cada uno comenzando con @ símbolo.

Vea el manual del phpDocumenter para más información

Ejemplo:

/**
* Encripta una cadena
*
* Llama al proceso de encriptación de una cadena de caracteres.
*
* @param string $string la cadena a encriptar.
* @param integer $type el tipo de encriptación a usar,
* los tipos validos estan especificados en
* el archivo ValidTypes.php.
*
* @return string el dato encriptado.
*/

Herramientas

Mejora tu código