Material de Milena

=Reglas de codificación y lineamientos de código en PHP=

Tabs o Espacios
En el contenido dentro de corchetes, siempre se identará este contenido con tabs.

Cabecera del achivo
Siempre es importante que todos los archivos .php inicien con una cabecera específica que indique información de la versión, autor de los últimos cambios, etc.

/**




 * @Control de presentación de los weblogs. "weblog.php"


 * @versión: 5.4.2     @modificado: 1 de Septiembre del 2006


 * @autor: Freddie





Comentarios en las funciones
Todas las funciones deben tener un comentario, antes de su declaración, explicando que hacen. Ningún programador debería tener que analizar el código de una función para conocer su utilidad. Tanto el nombre como el comentario que acompañe a la función deben bastar para ello.

En las funciones, es importante que el nombre denote su función inmediatamente. Cosas como imprimir_datos están bien, pero estaría mejor imprimir_datos_usuario. De igual manera, en los argumentos de las funciones queremos saber inmediatamente que estamos usando. Es mejor crear_usuario($nick, $email) que crear($n, $e).

Hacks
Los hacks que sea necesario colocar en el código deben, como las clases o funciones, ser comentados y en lo posible animar a otros programadores a reemplazarlos o mejorarlos por soluciones mejores.

Ubicación de archivos
En proyectos web o aplicaciones, generalmente se tendrán las siguientes carpetas:

* / Carpeta raiz: Aquí irán los archivos .php a los que accede el usuario directamente, interfaz, etc.   * clases: Una carpeta conteniendo exclusivamente las clases usadas en el proyecto * includes: Todos los archivos que sean llamados por otros .php en forma de módulos o de librerías de funciones. * db: En caso de tener la posibilidad de usar varias bases de datos, aquí colocaremos los .php que manejen esas características multicapa para cada sistema de datos soportado. * templates: En caso de usar un sistema de plantillas aquí guardaremos todos los archivos .tpl

Nombres de variables
Los nombres deben ser descriptivos y concisos. No usar ni grandes frases ni pequeñas abreviaciones para las variables. Siempre es mejor saber que hace una variable con sólo conocer su nombre. Esto aplica para los nombres de variables, funciones, argumentos de funciones y clases.

Todos los nombres deben estar en minúscula (Excepto con las clases, donde la primera letra ha de ser mayúscula). En caso de usar más de una palabra, ésta será separada por un signo de underscore "_".

Las variables siempre se asignan por valor, esto significa que cuando se asigna una expresión a una variable, el valor íntegro de la expresión original se copia en la variable de destino. Esto quiere decir que, por ejemplo, después e asignar el valor de una variable a otra, los cambios que se efectúen a una de esas variables no afectará a la otra.

Otra forma de asignar valores a las variables: asignar por referencia_ Esto significa que la nueva variable simplemente referencia (en otras palabras, "se convierte en un alias de" ó "apunta a") la variable original. Los cambios a la nueva variable afectan a la original, y viceversa. Esto también significa que no se produce una copia de valores; por tanto, la asignación ocurre más rápidamente. De cualquier forma, cualquier incremento de velocidad se notará sólo en los bucles críticos cuando se asignen grandes matrices u objetos.

Para asignar por referencia, simplemente se antepone un ampersandsigno "&" al comienzo de la variable cuyo valor se está asignando (la variable fuente)_ Por ejemplo, el siguiente trozo de código produce la salida 'Mi nombre es Bob' dos veces:



Algo importante a tener en cuenta es que sólo las variables con nombre pueden ser asignadas por referencia. <?php

$foo = 25;

$bar = &amp;$foo;     // Esta es una asignaci&oacute;n v&aacute;lida_

$bar = &amp;(24 * 7); // Inv&aacute;lida; referencia una expresi&oacute;n sin nombre_

function test {

return 25;

}

$bar = &amp;test;   // Inv&aacute;lida_

Siempre incluir corchetes
Es sencillo, si ibas a hacer esto:

if($cosa) funcion;

Mejor haz esto

if ($cosa)

{

funcion;

}

Corchetes o llaves. Donde colocarlas
Todos los corchetes van en una línea propia.

if (algo)

{

for (iteracion)

{

//código

}

}

while (condición)

{

funcion;

}

Poner espacios entre signos
Si tienes un signo binario, pon espacios a ambos lados. Tienes un signo unario, pon espacios a uno de sus lados. O en términos más simples, programa como si escribieras (bien) en español. Es algo muy sencillo que puede ayudar de gran manera en la lectura del código.

Esto está mal:

$a=0;

for($i=5;$i<=$j;$i++)

Esto está bien:

$a = 0;

for ($i = 5; $i <= $j; $i++)

Precedencia de operadores
Lo mejor es siempre usar paréntesis para estar seguro.

//¿Qué da esto como resultado?

$bool = ($i < 7 && $j > 8 || $k == 4);

//En cambio, si lo pongo así, es obvio y sencillo

$bool = (($i < 7) && (($j < 8) || ($k == 4)));

//Pero este es incluso mejor, porque está más optimizado y su lectura es superior

$bool = ($i < 7 && ($j < 8 || $k == 4));

Cadenas de texto entre comillas
PHP tiene dos formas de poner strings o cadenas de texto. Con comillas simples y con comillas dobles. La diferencia es que si usas comillas dobles y metes dentro del texto un nombre de variable, el compilador lo interpretará y reemplazará por su valor. Por ésta razón siempre has de usar comillas simples a menos que necesites hacer la interpolación de variables que permiten las dobles. Es difícil acostumbrarse porque ocurre sólo en PHP pero por eso es PHP.

Por supuesto hay casos especiales donde es mejor usar dobles comillas (Como cuando usas caracteres de escape \ intensivamente) así que siéntete con libertad de romper ésta regla cuando sea en pro de mejorar la lectura del código.

Constantes
Los identificadores de constantes deben declararse en mayúsculas.

El alcance de una constante es global, es decir, es posible acceder a ellas sin preocuparse por el ámbito de alcance.

Se puede definir una constante usando la función define_ Una vez definida, no puede ser modificada ni eliminada.

Solo se puede definir como constantes valores escalares (boolean, integer, float y string )_

Para obtener el valor de una constante solo es necesario especificar su nombre a diferencia de las variables, no se tiene que especificar el prefijo $. Tambien se puede utilizar la función constant, para obtener el valor de una constante, en el caso de que queramos expresarla de forma dinámica Usa la función get_defined_constants parar obtener una lista de todas las constantes definidas_

Nota: Las contantes y las variables (globales) se encuentran en un espacio de nombres distinto, esto implica que por ejemplo TRUE y $TRUE son diferentes_

Números dentro del código
A veces ponemos números especiales dentro de nuestro código para situaciones especiales. NO LO HAGAS. Si necesitas poner un número especial, conviértelo en constante y entonces impleméntalo. Ejemplo:

define('ARTICULOS_PORTADA', 10);

for ($i = 0; $i < ARTICULOS_PORTADA; $i++)

{

Operadores unarios de suma y resta.
Es sencillo, úsalos en una sola línea y a la derecha, ejemplo:

//Esto está MAL

$cosa = $matriz[$i--];

$otra = $matriz[++$y];

//Esto está BIEN

$y++;

$cosa = $matriz[$i];

$otra = $matriz[$y];

$i--;

Condicionales de una sola línea
Úsalas sólo para hacer cosas simples. En lo posible siempre utiliza if

//Sólo en estos casos son validas

$min = ($i < $j) ? $i : $j;

No uses variables sin inicializar
Si no tienes control sobre el valor de una variable, verifica que esté inicializada. Esto lo permite PHP de la siguiente manera:

//Mal hecho:

if ($cliente == 5) ...

//Bien hecho

if (isset($cliente) && $cliente == 5) ...

Pero sólo usa está opción cuando no tengas el control o no estés seguro que valor pueda tener la variable (Como en variables que llegan por parámetro o por GET, etc)

Instrucción “switch”
Cuando debas usarla, intenta seguir el siguiente estilo:

switch ($mode)

{

case 'modo1':

// Codigo de exito

break;

case 'modo2':

// Algoritmo que me retirará a los 25 años

break;

default:

// Código si todo falla

break;

}

Nota aclaratoria: todo lo que esté escrito en cursiva hace referencia a PHPDOCUMENTOR.

DocBlock
En phpDocumentor la documentación se distribuye en bloques DocBlock. Estos bloques siempre se colocan justo antes del elemento al que documentan y su formato es:

/**  <- Esta línea es ignorada function suma {  ... }
 * Descripción breve (una línea)
 * Descripción extensa. Todas las líneas que
 * sean necesarias
 * Todas las líneas comienzan con *
 * Todas las líneas comienzan con *
 * Este DocBlock documenta la función suma
 * Este DocBlock documenta la función suma

Los elementos que pueden ser documentados son:

define function class class vars include/require/include_once/require_once global variables

Además se puede incluir documentación globlal a nivel de fichero y clase mediante la marca @package

Marcas (tags)
Dentro de un bloque DocBlock se pueden incluir marcas que serán interpretadas por phpDocumentor de forma especial.

Hay una serie de marcas estándar que pueden ir dentro de todos los DocBlock: Marca 	Significado @access 	Si @access es 'private' no se genera documentación para el elemento (a menos que se indique explícitamente). Muy interesante si sólo se desea generar documentación sobre la interfaz (métodos públicos) pero no sobre la implementación (métodos privados). @author 	Autor del código @copyright 	Información sobre derechos @deprecated 	Para indicar que el elemento no debería utilizarse, ya que en futuras versiones podría no estar disponible. @example 	Permite especificar la ruta hasta un fichero con código PHP. phpDocumentor se encarga de mostrar el código resaltado (syntax-highlighted). @ignore 	Evita que phpDocumentor documente un determinado elemento. @internal inline {@internal}} 	Para incluir información que no debería aparecer en la documentación pública, pero sí puede estar disponible como documentación interna para desarrolladores. @link inline {@link} 	Para incluir un enlace (http://...) a un determinado recurso. @see 	Se utiliza para crear enlaces internos (enlaces a la documentación de un elemento). @since 	Permite indicar que el elemento está disponible desde una determinada versión del paquete o distribución. @version 	Versión actual del elemento

Ejemplo:

/** class Emilious_Sender {  //// aqui la implementacion de la clase }
 * Emilious Sender (class worker) :)
 * Envio de emails (MIME - multipart)
 * Codificacion de mensajes segun RFC-822
 * Utiliza la especificacion mime
 * Permite enviar ficheros adjuntos utilizando
 * Permite el envio a multiples destinatarios
 * @author Enrique Fernandez-Perera [Epsilon Eridani]
 * @author http://www.epsilon-eridani.com
 * @package Emilious_Sender
 * @author Enrique Fernandez-Perera [Epsilon Eridani]
 * @author http://www.epsilon-eridani.com
 * @package Emilious_Sender
 * @package Emilious_Sender

Declaración de funciones (elemento function) Marca 	Significado @global 	Permite especificar el uso de variables globales dentro de la función. @param 	Parámetros que recibe la función. Formato: @return 	Valor devuelto por la función. Formato:
 * @param tipo $nombre_var comentario
 * @return tipo comentario

NOTA: Tipos de datos en PHP (para indicar en @param, @return, etc...):

array string boolean integer float object mixed

Ejemplo:

/** function check_dir_email ($email) {   .... }
 * Verifica si una direccion de correo es correcta o no.
 * @return boolean true si la direccion es correcta
 * @param string $email direccion de correo
 * @param string $email direccion de correo

Ejemplo de documentación de un método privado (la documentación no aparecerá a menos que se especifique de forma explícita):

/** function encuentra_html_imagenes($dir_imagenes) {   .... }
 * localiza las imagenes dentro del contenido
 * @access private
 * @param string $dir_imagenes path al directorio de imagenes
 * @param string $dir_imagenes path al directorio de imagenes

Ejemplo de un comentario interno, @internal, que no aparecerá en la documentación de interfaz (documentación pública).

/** function body($body, $ctype="", $charset="") {
 * cuerpo del mensaje
 * Para mandar texto HTML, $body tiene que ser un array
 * de la forma (es preferible utilizar body_html):
 * $body['html'] = $texto_html;
 * $body['texto'] = $texto_plano; (opcional)
 * $body['dir_imagenes'] = $dir_imagenes; (opcional)
 * @internal Si $this->body_con_html==true el valor de $ctype no se tiene en cuenta.
 * @param mixed $body contenido del mensaje
 * @param string $ctype (opcional) mime-type del contenido (text/plain si es texto)
 * @param string $charset (opcional)
 * @param mixed $body contenido del mensaje
 * @param string $ctype (opcional) mime-type del contenido (text/plain si es texto)
 * @param string $charset (opcional)

Clases
Las clases serán colocadas en un archivo .php aparte, donde sólo se colocará el código de la clase. El nombre del archivo será el mismo del de la clase y siempre empezará en mayúscula. En lo posible, procurar que los nombres de clase tengan una sola palabra.

Las clases siguen las mismas reglas de las funciones, por tanto, debe colocarse un comentario antes de la declaración de la clase explicando su utilidad.

Variables de clase (atributos) Marca 	Significado @var 	Documenta los atributos de la clase. Formato:
 * @var tipo comentario

Ejemplo:

/** var $to;
 * array de destinatarios del mensaje
 * @var array destinatarios
 * @access private

COMO GENERAR LA DOCUMENTACIÓN CON PHP DOCUMENTOR
Generar la documentación

phpDocumentor permite generar la documentación de varias formas y en varios formatos.

Opciones para generar documentación:

1. Desde línea de comandos (php CLI - Command Line Interpreter) 2. Desde interfaz web (incluida en la distribución) 3. Desde código. Como phpDocumentor está desarrollado en PHP, podemos incluir su funcionalidad dentro de scritps propios.

¿Qué hay que especificar?

1. El directorio en el que se encuentra nuestro código. phpDocumentor se encarga de recorrer los subdirectorios de forma automática 2. Opcionalmente los paquetes (@pakage) que deseamos documentar, lista de ficheros incluidos y/o excluidos y otras opciones interesantes para personalizar la documentación. 3. El directorio en el que se generará la documentación 4. Si la documentación va a ser pública (sólo interfaz) o interna (en este caso aparecerán los bloques private y los comentarios @internal). 5. El formato de salida de la documentación

Formatos de salida

1. HTML a través de un buen número de plantillas predefinidas (podemos definir nuestra propia plantilla de salida) 2. PDF 3. XML (DocBook). Muy interesante puesto que a partir de este dialecto podemos transformar (XSLT) a cualquier otro utilizando nuestras propias reglas y hojas de estilo.