Cdigo

DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

Est prohibida la reproduccin total o parcial de esta publicacin por cualquier medio, ya sea mecnico o electrnico, incluyendo esta prohibicin la traduccin, uso de ilustraciones o planos, microfilmacin y almacenamiento en bases de datos, sin permiso de Telefnica Mviles S.A.

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

CONTENIDO 1 Formato de archivos PHP....................................................................................................5 1.1 General..........................................................................................................................5 1.2 Identacin......................................................................................................................5 1.3 Tamao mximo de lnea..............................................................................................5 1.4 Final de lnea.................................................................................................................5 2 Convenciones de Nombres.................................................................................................6 2.1 Clases............................................................................................................................6 2.2 Clases Abstractas.........................................................................................................6 2.3 Interfaces.......................................................................................................................6 2.4 Nombres de Archivo......................................................................................................7 2.5 Funciones y Mtodos....................................................................................................7 2.6 Variables........................................................................................................................9 2.7 Constantes....................................................................................................................9 3 Estilo de Cdigo.................................................................................................................10 3.1 Demarcacin de cdigo PHP......................................................................................10 3.2 Cadenas de Caracteres .............................................................................................10 3.2.1 Cadenas Literales de Caracteres.........................................................................10 3.2.2 Cadenas Literales de Caracteres que Contengan Apstrofos............................11 3.2.3 Sustitucin de Variables.......................................................................................11 3.2.4 Concatenacin de cadenas..................................................................................11 3.3 Arrays..........................................................................................................................12 3.3.1 Arrays Indexados Numricamente.......................................................................12 3.3.2 Arrays Asociativos................................................................................................13 3.4 Clases..........................................................................................................................14 3.4.1 Declaracin de clases..........................................................................................14 3.4.2 Variables de miembros de clase..........................................................................16 3.5 Funciones y Mtodos..................................................................................................16 3.5.1 Declaracin de Funciones y Mtodos.................................................................16 3.5.2 Uso de Funciones y Mtodos...............................................................................18 3.6 Sentencias de Control.................................................................................................19

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

3.6.1 If/Else/Elseif..........................................................................................................19 3.6.2 Switch...................................................................................................................21 3.7 Documentacin integrada...........................................................................................22 3.7.1 Formato de documentacin..................................................................................22 3.7.2 Archivos................................................................................................................22 3.7.3 Clases...................................................................................................................23 3.7.4 Funciones.............................................................................................................24

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

Control de Cambios

N Versin 1.0

Detalle de la Modificacin

Revisado por:

Aprobado por:

Fecha

En el presente control de cambios se presentara los 3 ltimos cambios realizados.

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

Formato de archivos PHP

1.1

General Para archivos que contengan nicamente cdigo PHP, la etiqueta de cierre ("?>") no est permitida. No es requerida por PHP, y omitirla evita la inyeccin de espacios en blanco en la respuesta.

1.2

Identacin La identacin suele estar compuesta por 4 espacios. Las tabulaciones no estn permitidas.

1.3

Tamao mximo de lnea La longitud recomendable para una lnea de cdigo es de 80 caracteres. El tamao mximo de cualquier lnea de cdigo PHP es de 120 caracteres.

1.4

Final de lnea El Final de Lnea sigue la convencin de archivos de texto Unix. Las lneas deben acabar con un carcter linefeed (LF). Los caracteres Linefeed estn representados con el nmero 10 ordinal, o el nmero 0x0A hexadecimal. Nota: No use retornos de carro (carriage returns, CR) como en las fuentes de Apple (0x0D) o la combinacin de retorno de carro - linefeed ( CRLF ) estndar para sistemas operativos Windows (0x0D, 0x0A).

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

Convenciones de Nombres

2.1

Clases Los nombres de clases pueden contener slo caracteres alfanumricos. Los nmeros estn permitidos en los nombres de clase, pero desaconsejados en la mayora de casos. Las barras bajas (_) estn permitidas solo como separador de ruta (el archivo " Acme/Db/Table.php " debe apuntar al nombre de clase " acme_Db_Table "). Si el nombre de una clase est compuesto por ms de una palabra, la primera letra de cada palabra debe aparecer en maysculas. Poner en maysculas las letras siguientes no est permitido, ej: "acme_PDF" no est permitido, mientras que "acme_Pdf " es admisible.

2.2

Clases Abstractas En general, las clases abstractas siguen las mismas convenciones que las clases, con una regla adicional: Los nombres de las clases abstractas deben acabar con el trmino, "Abstract", y ese trmino no debe ser precedida por un guin bajo. Ejemplo, Acme_Controller_Plugin_Abstract es considerado un nombre no vlido, pero Acme_Controller_PluginAbstract o Acme_Controller_Plugin_PluginAbs tract seran nombres vlidos.

2.3

Interfaces En general, las clases abstractas siguen las mismas convenciones que las clases, con una regla adicional:

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

Los nombres de las interfaces opcionalmente pueden acabar con el trmino, "Interface",pero trmino no debe ser precedida por un guin bajo. Ejemplo, Acme_Controller_Plugin_Interface es considerado un nombre no vlido, pero Acme_Controller_PluginInterface o Acme_Controller_Plugin_PluginInte rface serian nombres vlidos. Si bien esta regla no es necesaria, se recomienda encarecidamente su uso, ya que proporciona una buena referencia visual a los desarrolladores, como saber que archivos contienen interfaces en lugar de clases. 2.4 Nombres de Archivo Para cualquier otro archivo, slo caracteres alfanumricos, barras bajas (_) y guiones (-) estn permitidos. Los espacios en blanco estn estrictamente prohibidos. Cualquier archivo que contenga cdigo PHP debe terminar con la extensin " .php ", con la excepcin de los scripts de la vista. Los siguientes ejemplos muestran nombres de archivo admisibles para clases: Acme/Db.php Acme/Controller/Front.php Acme/View/Helper/FormRadio.php Los nombres de archivo deben apuntar a nombres de clases como se describe arriba.

2.5

Funciones y Mtodos Los nombres de funciones pueden contener nicamente caracteres alfanumricos. Los guiones bajos (_) no estn permitidos. Los nmeros estn permitidos en los nombres de funcin pero no se aconseja en la mayora de los casos.

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

Los nombres de funciones deben empezar siempre con una letra minscula. Cuando un nombre de funcin consiste en ms de una palabra, la primera letra de cada nueva palabra debe estar en maysculas. Esto es llamado comnmente como formato "camelCase". Por norma general, se recomienda la elocuencia. Los nombres de funcin deben ser lo suficientemente elocuentes como para describir su propsito y comportamiento. Estos son ejemplos de nombres de funciones admisibles:

filterInput() getElementById() widgetFactory() Para la programacin orientada a objetos, los mtodos de acceso para las instancias o variables estticas deben ir antepuestos con un "get" o un "set". Al implementar el patrn de diseo, tales como el patrn singleton o el patrn factory, el nombre del mtodo deben contener en la prctica el nombre del patrn para describir su comportamiento de forma ms completa. Para el caso en que los mtodos son declarados con el modificador "private" o "protected", el primer carcter del nombre de la variable debe ser una barra baja (_). Este es el nico uso admisible de una barra baja en un nombre de mtodo. Los mtodos declarados como pblicos no deberan contener nunca una barra baja. Las funciones de alcance global (tambin llamadas "funciones flotantes") estn permitidas pero desaconsejadas en la mayora de los casos. Considere envolver esas funciones en una clase esttica.

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

2.6

Variables Los nombres de variables pueden contener caracteres alfanumricos. Las barras bajas (_) no estn permitidas. Los nmeros estn permitidos en los nombres de variable pero no se aconseja en la mayora de los casos.

Para las variables de instancia que son declaradas con el modificador "private" o "protected", el primer carcter de la variable debe ser una nica barra baja (_). Este es el nico caso admisible de una barra baja en el nombre de una variable. Las variables declaradas como "public" no pueden empezar nunca por barra baja. Al igual que los nombres de funciones (ver seccin 3.3), los nombres de variables deben empezar siempre con una letra en minscula y seguir la convencin "camelCaps". Por norma general, se recomienda la elocuencia. Las variables deberan ser siempre tan elocuentes como prcticas para describir los datos que el desarrollador pretende almacenar en ellas. Variables escuetas como " $i " y " $n " estn desaconsejadas, salvo para el contexto de los bucles ms pequeos. Si un bucle contiene ms de 20 lneas de cdigo, las variables de ndice deberan tener nombres ms descriptivos.

2.7

Constantes Las constantes pueden contener tanto caracteres alfanumricos como barras bajas (_). Los nmeros estn permitidos. Todas las letras pertenecientes al nombre de una constante deben aparecer en maysculas.

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

Las palabras dentro del nombre de una constante deben separarse por barras bajas (_). Por ejemplo, EMBED_SUPPRESS_EMBED_EXCEPTION est permitido,

pero EMBED_SUPPRESSEMBEDEXCEPTION no. Las constantes deben ser definidas como miembros de clase con el modificador "const". Definir constantes en el alcance global con la funcin "define" est permitido pero no recomendado.

Estilo de Cdigo

3.1

Demarcacin de cdigo PHP El cdigo PHP debe estar delimitado siempre por la forma completa de las etiquetas PHP estndar:

<?php ?>

Las etiquetas cortas no se permiten nunca. Para archivos que contengan nicamente cdigo PHP, la etiqueta de cierre debe omitirse siempre. 3.2 Cadenas de Caracteres

3.2.1 Cadenas Literales de Caracteres Cuando una cadena es literal (no contiene sustitucin de variables), el apstrofo o "comilla" debera ser usado siempre para delimitar la cadena:

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

$a = 'Example String';

3.2.2 Cadenas Literales de Caracteres que Contengan Apstrofos Cuando una cadena literal de caracteres contenga apstrofos, es permitido delimitar la cadena de caracteres con "comillas dobles". Esto es especialmente til para sentencias SQL:

$sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'"; 3.2.3 Sustitucin de Variables La sustitucin de variables est permitida en cualquiera de estas formas:

greeting = "Hello $name, welcome back!"; $greeting = "Hello {$name}, welcome back!"; Por consistencia, esta forma no est permitida:

$greeting = "Hello ${name}, welcome back!";

3.2.4 Concatenacin de cadenas Las cadenas deben ser concatenadas usando el operador punto ("."). Un espacio debe aadirse siempre antes y despus del operador "." para mejorar la legibilidad:

$company = 'Acme' . ' ' . 'Technologies';

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

Al concatenar cadenas con el operador ".", se recomienda partir la sentencia en mltiples lneas para mejorar la legibilidad. En estos casos, cada lnea sucesiva debe llevar un margen de espacios en blanco de forma que el operador "." est alineado bajo el operador "=":

$sql = "SELECT `id`, `name` FROM `people` " . "WHERE `name` = 'Susan' " . "ORDER BY `name` ASC "; 3.3 Arrays

3.3.1 Arrays Indexados Numricamente No estn permitidos nmeros negativos como ndices. Un array indexado puede empezar por cualquier valor no negativo, sin embargo, no se recomiendan ndices base distintos a 0. Al declarar arrays indexados con la funcin array, un espacio de separacin deben aadirse despus de cada coma, para mejorar la legibilidad:

$sampleArray = array(1, 2, 3, 'Acme', 'Studio'); Se permite declarar arrays indexados multilnea usando la construccin "array". En este caso, cada lnea sucesiva debe ser tabulada con cuatro espacios de forma que el principio de cada lnea est alineado: $sampleArray = array(1, 2, 3, 'Acme', 'Studio', $a, $b, $c, 56.44, $d, 500);

Alternativamente, el elemento inicial del array puede comenzar en la siguiente lnea. Si es as, debe ser alineado en un nivel de sangra superior

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

a la lnea que contiene la declaracin del array, y todas las sucesivas lneas deben tener la misma indentacin, el parntesis de cierre debe ser en una nueva lnea al mismo nivel de indentacin que la lnea que contiene la declaracin del array:

$sampleArray = array( 1, 2, 3, 'Acme', 'Studio', $a, $b, $c, 56.44, $d, 500, ); Al utilizar esta ltima declaracin, recomendamos la utilizacin de una coma detrs del ltimo elemento de la matriz, lo que minimizar el impacto de aadir nuevos elementos en las siguientes lneas, y ayuda a garantizar que no se produzcan errores debido a la falta de una coma.

3.3.2 Arrays Asociativos

Al declarar arrays asociativos con la construccin array, se recomienda partir la declaracin en mltiples lneas. En este caso, cada lnea sucesiva debe ser tabulada con cuatro espacios de forma que tanto las llaves como los valores estn alineados:

$sampleArray = array('firstKey' => 'firstValue', 'secondKey' => 'secondValue');

Alternativamente, el elemento inicial del array puede comenzar en la siguiente lnea. Si es as, debe ser alineado en un nivel de sangra superior a la lnea que contiene la declaracin del array, y todas las sucesivas lneas deben tener la mismo indentacin, el parntesis de cierre debe ser en una nueva lnea al mismo nivel de indentacin que la lnea que contiene la declaracin del array: Para mejor legibilidad, los diversos operadores de asignacin "=>" deben ser rellenados con espacios en blanco hasta que se alineen.

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

$sampleArray = array( 'firstKey' => 'firstValue', 'secondKey' => 'secondValue', );

Al utilizar esta ltima declaracin, recomendamos la utilizacin de una coma detrs del ltimo elemento de la matriz, lo que minimizar el impacto de aadir nuevos elementos en las siguientes lneas, y ayuda a garantizar que no se produzcan errores debido a la falta de una coma.
3.4 3.4.1 Clases Declaracin de clases Las Clases deben ser nombradas de acuerdo a la convencin de nombres (Seccin 2). La llave "{" deber escribirse siempre en la lnea debajo del nombre de la clase ("one true brace"). Cada clase debe contener un bloque de documentacin acorde con el estndar de PHPDocumentor. Todo el cdigo contenido en una clase debe ser separado con cuatro espacios. nicamente una clase est permitida por archivo PHP. Incluir cdigo adicional en archivos de clase est permitido pero esta desaconsejado. En archivos de ese tipo, dos lneas en blanco deben separar la clase de cualquier cdigo PHP adicional en el archivo de clase. A continuacin se muestra un ejemplo de una declaracin de clase que es permitida:

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

/** * Bloque de Documentacin aqu */ class SampleClass { // el contenido de la clase // debe separarse con cuatro espacios }

Las clases que extiendan otras clases o interfaces deberan declarar sus dependencias en la misma lnea siempre que sea posible.

class SampleClass extends FooAbstract implements BarInterface { }

Si como resultado de esas declaraciones, la longitud de la lnea excede la longitud del Tamao mximo de lnea, se debe romper la lnea antes de la palabra clave "extends" y / o "implements" e indentarlo con un nivel de indentacin (4 espacios).

class SampleClass extends FooAbstract implements BarInterface { }

Si la clase implementa mltiples interfaces y la declaracin excede el tamao mximo de lnea, se debe romper la lnea antes de cada coma separando las interfaces e indentar los nombres hasta alinearnos.

class SampleClass implements BarInterface, BazInterface { }

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

3.4.2

Variables de miembros de clase Las variables de miembros de clase deben ser nombradas de acuerdo con las convenciones de nombrado de variables (Seccin 2). Cualquier variable declarada en una clase debe ser listada en la parte superior de la clase, por encima de las declaraciones de cualquier mtodo.

La construccin var no est permitida. Las variables de miembro siempre declaran su visibilidad usando uno los modificadores private , protected , o public. Dar acceso a las variables de miembro declarndolas directamente como public est permitido pero no se aconseja en favor de accesor methods (set & get). 3.5 Funciones y Mtodos 3.5.1 Declaracin de Funciones y Mtodos Las Funciones deben ser nombradas de acuerdo a las convenciones de nombrado (Seccin 2). Los mtodos dentro de clases deben declarar siempre su visibilidad usando un modificador private , protected , o public . Como en las clases, la llave "{" debe ser escrita en la lnea siguiente al nombre de la funcin ("one true brace" form). No est permitido un espacio entre el nombre de la funcin y el parntesis de apertura para los argumentos. Las funciones de alcance global no estn permitidas. Lo siguiente es un ejemplo de una declaracin admisible de una funcin en una clase:

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

/** * Bloque de Documentacin aqu */ class Foo { /** * Bloque de Documentacin aqu */ public function bar() { // el contenido de la funcin // debe separarse con cuatro espacios } }

Si los argumentos exceden el tamao mximo de lnea, se debe ingresar saltos de lnea. Adems los argumentos de la funcin deben estar intentados un nivel ms all de la declaracin del mtodo o funcin. Un salto de lnea ocurre antes del parntesis de cierre, el cual debe ser colocado en la misma lnea que la llave de apertura de la funcin o el mtodo con un espacio que los separa, y al mismo nivel de indentacin que la funcin o el mtodo de declaracin. El siguiente es un ejemplo de una de esas situaciones:

/** * Documentation Block Here */ class Foo { /** * Documentation Block Here */ public function bar($arg1, $arg2, $arg3, $arg4, $arg5, $arg6 ){ // all contents of function // must be indented four spaces } }

La llamada por referencia est estrictamente prohibida.

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

El valor de retorno no debe estar indicado entre parntesis. Esto podra afectar a la legibilidad, adems de romper el cdigo si un mtodo se modifica posteriormente para que devuelva por referencia.

/** * Bloque de Documentacin aqu */ class Foo { /** * INCORRECTO */ public function bar() { return($this->bar); } /** * CORRECTO */ public function bar() { return $this->bar; } }

3.5.2 Uso de Funciones y Mtodos Los argumentos de la funcin tendran que estar separados por un nico espacio posterior despus del delimitador coma. A continuacin se muestra un ejemplo de una invocacin admisible de una funcin que recibe tres argumentos:

threeArguments(1, 2, 3);

La llamada por referencia est estrictamente prohibida. Vea la seccin de declaraciones de funciones para el mtodo correcto de pasar argumentos por referencia. Al pasar arrays como argumentos a una funcin, la llamada a la funcin puede incluir el indicador "hint" y puede separarse en mltiples lneas para

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

aumentar la legibilidad. En esos casos, se aplican las pautas normales para escribir arrays:

threeArguments(array(1, 2, 3), 2, 3); threeArguments(array(1, 2, 3, 'Acme', 'Studio', $a, $b, $c, 56.44, $d, 500), 2, 3); threeArguments(array( 1, 2, 3, 'Acme', 'Studio', $a, $b, $c, 56.44, $d, 500 ), 2, 3);

3.6

Sentencias de Control 3.6.1 If/Else/Elseif Las sentencias de control basadas en las construcciones if y elseif deben tener un solo espacio en blanco antes del parntesis de apertura del condicional y un solo espacio en blanco despus del parntesis de cierre. Dentro de las sentencias condicionales entre parntesis, los operadores deben separarse con espacios, por legibilidad. Se aconseja el uso de parntesis internos para mejorar la agrupacin lgica en expresiones condicionales ms largas. La llave de apertura "{" se escribe en la misma lnea que la sentencia condicional. La llave de cierre "}" se escribe siempre en su propia lnea. Cualquier contenido dentro de las llaves debe separarse con cuatro espacios en blanco.

if ($a != 2) { $a = 2; }

Si las sentencias condicionales exceden el tamao mximo de lnea y tiene varias clusulas, se debe ingresar saltos de lnea. En tal caso, romper la lnea antes de un operador lgico, e indentar la lnea de tal forma que se

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

alinee con el primer caracter de la clusula condicional. El parntesis de cierre en el condicional ser colocado en una lnea con la llave de apertura, con un espacio que separe a los dos, a un nivel de sangra equivalente a la instruccin de control de apertura.

if (($a == $b) &amp;&amp; ($b == $c) || (Foo::CONST == $d) ){ $a = $d; }

La intencin de este formato de declaracin es para evitar problemas al aadir o eliminar las clusulas condicionales en revisiones posteriores. Para las declaraciones "if" que incluyan "elseif" o "else", las convenciones de formato son similares a la construccin "if". Los ejemplos siguientes demuestran el formato correcto para declaraciones "if" con construcciones "else" y/o "elseif":

if ($a != 2) { $a = 2; } else { $a = 7; } if ($a != 2) { $a = 2; } elseif ($a == 3) { $a = 4; } else { $a = 7; } if (($a == $b) &amp;&amp; ($b == $c) || (Foo::CONST == $d) ){ $a = $d; } elseif (($a != $b) || ($b != $c) ){

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

$a = $c; } else { $a = $b; }

PHP permite escribir sentencias sin llaves -{}- en algunas circunstancias. Este estndar de cdigo no hace ninguna diferenciacin- toda sentencia "if", "elseif" o "else" debe usar llaves. El uso de la construccin "elseif" est permitido pero no se aconseja, en favor de la combinacin "else if".

3.6.2 Switch Las declaraciones de control escritas con la declaracin "switch" deben tener un nico espacio en blanco antes del parntesis de apertura del condicional y despus del parntesis de cierre. Todo contenido dentro de una declaracin "switch" debe separarse usando cuatro espacios. El contenido dentro de cada declaracin "case" debe separarse usando cuatro espacios adicionales.

switch ($numPeople) { case 1: break; case 2: break; default: break; }

La construccin default no debe omitirse nunca en una declaracin switch.

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

3.7

Documentacin integrada 3.7.1 Formato de documentacin Todos los bloques de documentacin ("docblocks") deben ser compatibles con el formato de phpDocumentor. Describir el formato de phpDocumentor est fuera del alcance de este documento. Para ms informacin, visite: http://phpdoc.org/ Todos los archivos de clase deben contener un bloque de documentacin "a nivel de archivo" al principio de cada archivo y un bloque de documentacin "a nivel de clase" inmediatamente antes de cada clase. Ejemplo de estos bloques de documentacin pueden encontrarse debajo.

3.7.2 Archivos

Cada archivo que contenga cdigo PHP debe tener un bloque de documentacin al principio del archivo que contenga como mnimo las siguientes etiquetas phpDocumentor:

/** * Descripcin corta del fichero * * Descripcin larga del fichero (si la hubiera)... * * LICENSE: Some license information * * @category Acme * @package Acme_Magic * @subpackage Wand * @copyright Copyright (c) 2005-2011 Acme Technologies USA Inc. (http://www.acme.com) * @license http://framework.acme.com/license BSD License * @version $Id:$ * @link http://framework.acme.com/package/PackageName

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

* @since */

File available since Release 1.5.0

La anotacin @category debe tener un valor de "Acme". La anotacin @package debe ser asignada, y debera ser equivalente al componente al que pertenece el archivo. Tpicamente, este slo tendr 2 segmentos, el prefijo Acme y el nombre del componente. La anotacin @subpackage es opcional. Si lo hay, debe ser el nombre de subcomponente, menos el prefijo de clase. En el ejemplo anterior, el supuesto es que la clase descrita es "Acme_Magic_Wand", o use el classname como parte de su prefijo. 3.7.3 Clases Cada clase debe contener un bloque de documentacin que contenga como mnimo las siguientes etiquetas phpDocumentor:

/** * Descripcin corta de la clase * * Descripcion larga de la clase (si la hubiera)... * * @category Acme * @package Acme_Magic * @subpackage Wand * @copyright Copyright (c) 2005-2011 Acme Technologies USA Inc. (http://www.acme.com) * @license http://framework.acme.com/license BSD License * @version Release: @package_version@ * @link http://framework.acme.com/package/PackageName * @since Class available since Release 1.5.0 * @deprecated Class deprecated in Release 2.0.0 */

La anotacin @category debe tener un valor de "Acme". La anotacin @package debe ser asignada, y debera ser equivalente al componente al que pertenece la clase.

Cdigo
DOCUMENTO DE BUENAS PRCTICAS DE PROGRAMACIN PARA PHP

DSI-GOE-DOC-001 1.0

Versin Emisin

La anotacin @subpackage es opcional. Si lo hay, debe ser el nombre de subcomponente, menos el prefijo de clase. En el ejemplo anterior, el supuesto es que la clase descrita es "Acme_Magic_Wand", o use el classname como parte de su prefijo.

3.7.4 Funciones Cada funcin, incluyendo mtodos de objeto, debe contener un bloque de documentacin que contenga como mnimo:
Una descripcin de la funcin

Todos los argumentos Todos los posibles valores de retorno

No es necesario incluir la etiqueta "@access" si el nivel de acceso es conocido de antemano por el modificador "public", "private", o "protected" usado para declarar la funcin. Si una funcin/mtodo puede lanzar una excepcin, utilice @throws para todos los tipos de excepciones conocidas:

@throws exceptionclass [description]