Manual de estilo del programador PHP

Transcripción

13 de agosto de 2997
Manual de estilo del
programador PHP
Desarrollo. Área de PHP
Índice
Control de cambios..................................................................... 3
Introducción y objetivos ............................................................. 4
Indentación .............................................................................. 4
Documentación y comentarios .....................................................5
Estilo y metodología .........................................................................................................5
Cabeceras de ficheros ....................................................................................................... 6
Métodos y funciones..........................................................................................................7
Nombre de los ficheros ...............................................................7
Nomenclatura............................................................................ 8
Espaciado ................................................................................. 9
Asignaciones y operaciones...............................................................................................9
Funciones y métodos ........................................................................................................ 9
Estructuras de control ..................................................................................................... 10
PHP Tags ................................................................................ 10
Codificación y caracteres .......................................................... 11
Buenas prácticas ..................................................................... 11
INFORMACIÓN CONFIDENCIAL
No se permite su reproducción, modificación, comunicación o distribución sin autorización del propietario
BIKO© Todos los derechos reservados
Pol. Industrial Mutilva Baja, Calle E, Nº 5 1ºC, Mutilva Baja
Tel. 948 072222 – Fax. 948 072223 – [email protected] - http://www.biko2.com
2
Control de cambios
Fecha
Autor
13/08/2007 Fran Naranjo
Descripción
Primera revisión del documento
Versión
1.0
3
Introducción y objetivos
El presente documento mostrará las pautas que debe seguir todo programador de
PHP a la hora de realizar los programas en este lenguaje. De esta forma, se
conseguirá un código lo más homogéneo posible que permita un entorno conocido
para cualquier desarrollador.
Indentación
Se usarán tabulaciones (tecla Tab) para cada nivel de indentación del código
fuente, no siendo nunca sustituidos por espacios. Se recomienda que cada
tabulación ocupe el equivalente a 4 espacios, aunque se deja de mano del
programador
Se
usará
siempre
una
y
cuando
indentación
de
la
separación
código
al
sea
estilo
mediante
K&R,
tabulaciones.
Kernigham&Ritchie
(http://en.wikipedia.org/wiki/Indent_style) según se indica para las estructuras,
obviando la declaración de funciones ya que contienen motivos históricos
arraigados desde C. En este estilo, las llaves se colocarán en la misma línea que el
elemento al que pertenece y se cierra en la línea siguiente al mismo nivel; su
contenido se indenta con un tabulador.
Ejemplo:
class CMSApplication {
function CMSApplication() {
$this->_startup_done = false;
$this->_shutdown_done = false;
}
}
4
Cada instrucción debe ocupar al menos una línea. No se usará la misma línea para
dos instrucciones diferentes. Esta regla viene dada principalmente para estructuras
de control como por ejemplo if y que únicamente tiene una instrucción; si bien las
llaves son opcionales, la instrucción debe ir en una línea distinta y tabulada.
Para el caso de una línea con una única instrucción y que quiera escribirse en más
de una línea, las siguientes a la primera se indentarán con un tabulador. Deberá
intentar no superarse 80 caracteres por línea.
Ejemplo:
$options = array(
'cacheDir' => $cache_default_path.'/html/',
'caching' => $cache_enabled,
'lifeTime' => $cache_default_expire_time',
'fileNameProtection' => false,
'hashedDirectoryLevel ' => 0
);
Documentación y comentarios
Estilo y metodología
La documentación del código se realizará mediante la sintaxis definida por Doxygen
(http://www.stack.nl/~dimitri/doxygen/).
Doxygen analiza el código fuente en busca de marcas especiales en los comentarios
como
puede
leerse
en
la
documentación,
http://www.stack.nl/~dimitri/doxygen/docblocks.html, y usaremos la que añade un
asterisco (*) en la primera línea del comentario.
5
Por ejemplo:
/**
* Este es el comentario a usar por Doxygen
*/
Existen ciertos comandos que pueden usarse para indicar a Doxygen cierta
información relevante y que permite enlazar con el propio código. Estos comandos
se identifican porque comienzan con una arroba (@). Puede encontarse la definición
y
descripción
de
todos
ellos
en
la
siguiente
dirección
web:
http://www.stack.nl/~dimitri/doxygen/commands.html.
Algunos que se usarán con más frecuencia son (entre [ ] el texto a completar):
●
@author [nombre]: indica el autor
●
@ingroup [grupo]: indica el grupo o paquete al que pertenece el código
●
@date [fecha]: indica la fecha
●
@var [tipo]: indicar el tipo de variable
●
@param [variable] [descripción]: explica la naturaleza y uso del parámetro
de una función
●
@return [descripción]: descripción de la variable de retorno
●
@retval [variable] [descripción]: tipo de variable de retorno y su descripción
●
@public: para indicar que una variable o método es público
●
@private: para indicar que una variable o método es privado
●
@static: para indicar que una variable o método es estático
Cabeceras de ficheros
Cada fichero, bien sea una clase, un conjunto de funciones o un código sin
jerarquía, debe incluir en su inicio (cabecera) una descripción de su objetivo,
6
incluyendo además por lo menos el nombre del autor, la fecha y grupo o paquete al
que pertenece (si es aplicable).
Ejemplo (completo):
/**
* Realiza labores de maquetacion y calculo de los elementos de paginacion
* Distingue entre páginas a seleccionar y la página seleccionada, dando la
* opcion de establecer representaciones distintas. El resto del código HTML,
* anterior y posterior, corre a manos del programador.
*
* @brief Maquetación y cálculo de paginaciones
* @author Fran Naranjo
* @package Publisher
* @date 2005-11
*/
Métodos y funciones
Cada método y función deberá llevar un comentario indicando su función. Además,
se indicará de qué tipo es (público, privado o estático si es aplicable), qué
parámetros tiene y valor de retorno. Estos dos últimos elementos son muy
importantes, ya que PHP no está tipado y por lo tanto será de referencia indicar en
esta parte qué parámetros se deben pasar y de qué forma, así como el valor que se
retorna.
Ejemplo (completo):
7
/**
* Establece los filtros para aceptar o denegar nodos a presentar
* Se establecen 3 tipos de filtros:
*
- accept: $nodes contiene un array con los nodos a aceptar.
*
Únicamente se presentarán estos nodos
*
- reject: $nodes contiene un array con los nodos a denegar.
*
El resto de nodos que no coincidan en esta lista, se mostrarán
*
- all: se aceptan todos los nodos. El contenido de $nodes se descarta
*
* @param $tipo tipo de filtro: "accept", "reject" o "all"
* @param $nodes array con nodos. Úicamente para los tipos "accept" o "reject"
* @return void
* @public
*/
function setFilter($tipo, $nodes = array()) {
}
Nombre de los ficheros
Los siguientes ficheros deberán seguir ciertas pautas en su nomenclatura:
●
Clases: nombre de la
clase
terminado en .class.php. Por
ejemplo,
Menus.class.php
●
Ficheros HTML o XHTML: terminados en .html. Por ejemplo, cabecera.html
●
Ficheros de XTemplate: terminados en .xtpl. Por ejemplo: menu.xtpl
●
Includes de php: terminados en .inc.php
También se permitirán includes de php de la forma inc_[nombre].php aunque se
prefiere la forma indicada anteriormente.
Nomenclatura
Todas las funciones y variables (incluyendo métodos y propiedades de las clases)
comenzarán con letra minúscula y para palabras compuestas se usará una letra
mayúscula para cada palabra. Se evitará el uso de guiones bajos (_) y repetir dos o
más mayúsculas seguidas. Se debe intentar no usar nombres demasiado largos,
8
pero sin comprometer el significado de la función.
Ejemplo:
function getRenderFromFilename($filename)
Para asignación y recuperación de variables o valores, se preferirá el uso de las
palabras set y get respectivamente.
Todos aquellos métodos o propiedades de una clase que se consideren privados,
deberán comendar con un "guión bajo" (_).
Ejemplo:
function _setItems($items) {
$this->_items = $items;
}
Para acceder a los elementos de un array mediante su clave, usaremos literales de
texto.
Ejemplo:
Usar $tabla['id'] y no $tabla[id]
Espaciado
Se deben separar todos los elementos y estructuras de modo que se permita una
fácil lectura. Separando cada elemento de los demás mediante espacios, cambios
de línea o tabuladores mejoraremos esta lectura.
9
Asignaciones y operaciones
Usar un espacio entre cada término y operador utilizado.
Ejemplos:
●
●
●
●
$a = 4 * $b + calcula();
$c += 4;
$this->final = $inicio . $medio . $final;
[En un array] 'index' => 'value'
Funciones y métodos
Cada uno de los parámetros de una función o método deben estar separados por un
espacio
tras
la
coma
que
los
diferencia,
pero
no
antes.
Los paréntesis con los parámetros de una función o método (aunque no contengan
nada) deberán posicionarse junto a la función, al igual que en la llamada a la
misma.
La llave de inicio deberá estar en esta misma línea y separada por un espacio.
Ejemplo:
function getRenderSingle($pag_offset, $texto) {
}
Estructuras de control
Deberán seguirse las indicaciones marcadas para las funciones, asignaciones y
operaciones. Además, para el caso de la sentencia for, deberán separarse todos sus
elementos
Ejemplos:
●
●
●
while($a < 0 && $b > 100)
for($i = 0; $i < $final; $i++)
if($a != 1)
10
PHP Tags
Para identificar código PHP, se usarán el tag de apertura <?php y el tag de cierre ?
>. Además para imprimir valores directamente en código HTML, puede usarse el
tag <?= ?>
Debe
evitar
usarse
el
resto
de
posibilidades
disponibles
http://www.php.net/manual/en/language.basic-syntax.php.
Si se está desarrollando código "en línea" sobre el código HTML (por ejemplo, sin
usar plantillas XTemplate, sino directamente) y debemos incluir código HTML,
evitaremos el uso de print o echo a favor de cerrar el tag php y volver a abrirlo al
finalizar ya que ayudará en gran manera al entender el código y a realizar
posteriores cambios parciales o totales.
Ejemplo:
if($ponerMenu) {
?><ul id="menu"><?php
foreach($entradas AS $entrada) {
?><li class="opcion"><?= entrada ?></li><?php
}
?></ul><?php
}
Codificación y caracteres
Excepto que el proyecto en el que se esté trabajando tenga algún requerimiento
especial y por lo tanto el servidor esté configurado de esa forma, se utilizará una
codificación UTF-8. Por lo tanto, deberá configurarse tanto el editor como el sistema
para generar y modificar ficheros con esta codificación.
11
Se usarán saltos de línea ("intros") al estilo UNIX, también conocido como "\n"
evitando otras combinaciones como las Windows/DOS/MAC ("\r\n").
Se deberá usar la comilla simple (') para identificar caracteres utilizando la
concatenación para enlazar con variables, menos en los casos en los que el uso de
las comillas dobles (") es necesario, por ejemplo para usar caracteres especiales o
de control ("\n", "\t", etc) o cuando se use la comilla simple repetidas veces (por
ejemplo un SQL: $query = "SELECT * FROM tabla WHERE estado='abierto'";)
Buenas prácticas
En este apartado se detallarán diversas acciones que se consideran convenientes a
la hora de programar en PHP.
Antes de realizar asignaciones con variables que se posible que no tengan valor o
que incluso no estén definidas, realizar una comprobación con isset() y actuar en
consecuencia al resultado de esta función. Por ejemplo, variables pasadas por GET
o POST, valores en un array, etc
No abusar del uso de las funciones include_once o require_once ya que es posible
que nos sirva con include o require. El uso de require_once es muy costoso
computacionalmente y no se recomienda su uso excepto en casos que lo requieran.
Mejor usar include antes que require si es posible.
Cuando se definen tablas (arrays) con varias entradas o con varios niveles, utilizar
indentación y una línea para cada entrada. Harán el código más claro y fácil de
cambiar.
Ejemplo:
12
$myArray = array(
'key1' => 'valor1',
'key2' => array(
'key2_1' => 'valor2_1',
'key2_2' => 'valor2_2'
)
);
Utilizar funciones "preg" en vez de las "ereg" ya que son mucho más rápidas y
eficientes. No usar expresiones regulares en cadenas de texto estáticas.
Usar explode(), es mucho más eficiente que split(), str_replace(), strpos() y strtr().
Utilizar path completos en vez de relativos al usar ficheros, se reduce el tiempo que
el procesador del servidor tiene que traducir esa dirección.
13

Manual de estilo del programador PHP

Transcripción

Documentos relacionados

Nextel Exclusivo a Distribuidores y Franquiciatarios

Agenda Verano 2014 - Ayuntamiento de ARANGUREN

1. Inversión: Empresas Internacionales: 200 Bs (o su equivalente 29