Para programar en PHP utilizaremos el estándar recomendado por la empresa Zend (creadora del lenguaje PHP).
El estándar en el código de programación es muy importante en cualquier proyecto, principalmente si este involucra muchos desarrolladores.
Esto nos asegura que el código es de alta calidad, contiene una cantidad baja de bugs y es fácil de mantener.
El estándar recomendado incluye los siguientes tópicos:
- Formato del archivo PHP
- Convención en los nombres
- Estilo en el código
- Documentación
Formato del archivo PHP
Para aquellos archivos que contienen sólo código PHP los tags de demarcación (“
Identación
La identación consistirá en cuatro espacios en blanco y la tabulación no estará permitida.
Largo máximo de la línea
El largo máximo ideal de una linea de código es de 80 caractéres, esto nos permite una cómoda lectura del mismo. El máximo permitido por PHP es de 120 caractéres.
Fin de línea
El fin de línea seguirá la convención de texto de Unix. La línea debe de terminar con el caracter linefeed (LF) representado con el ordinal 10 ó hexadecimal 0×0A.
No utilice el retorno de carro (Enter) (CF) que es un convecionalismo de los Sistemas operativos de Apple ó el retorno de carro / linefeed (CRLF) que es de Windows.
Convención en los nombres
Clases
El nombre de las clases debe estar compuesto de caractéres alfanuméricos. El catacter Underscore (“_”) solo es permitido para remplazar al separador en el path del archivo, por ejemplo: “Zend/Db/Table.php” quedaría como “Zend_Db_Table”.
Si el nombre de la clase está comprimida en más de una palabra la primera letra debe de ser mayúscula. Letras mayúsculas seguidas no son permitidas.
Ejemplo: “Zend_PDF” no es permitido mientras que “Zend_Pdf” si lo es.
Archivos
En el nombre de los archivos se permite caractéres alfanuméricos, Underscore, dash (“-”), pero no está permitido el espacio en blanco.
Funciones y Métodos
El nombre de las funciones debe estar compuesto de caractéres alfanuméricos, el catactér Underscore no está permitido, siempre tiene que comenzar con letra minúscula, si el nombre consiste en más de una palabra la primera letra de cada una de ella deberá ser mayúscula, por ejemplo: getElementById(), widgetFactory().
Un correcto empleo de verbos describe mejor el propósito y comportamiento de las funciones.
En caso de la programación orientada a objetos suele colocarse prefijos como “get” ó “set”, asi como también el nombre de los patrones. En el caso que el método sea “private” ó “protected” el primer caractér debe ser Underscore ( único caso permitido ), aquelllos declarados “public” no llevan Underscore.
Variables
El nombre de las variables debe estar compuesto de caractéres alfanuméricos, el catactér Underscore no está permitido. En el caso que sean declaradas “private” ó “protected” el primer caractér debe ser Underscore ( único caso permitido ), aquelllas declaradas “public” no llevan Underscore.
Siempre tiene que comenzar con letra minúscula, si el nombre consiste en más de una palabra la primera letra de cada una de ella deberá ser mayúscula. Un correcto empleo de verbos describe mejor la variable. Por ejemplo aquellas llamadas “$i” y “$n” serían permitidas en caso de que el algortimo sobrepasara las 20 líneas.
Constantes
Está permitido caractéres alfanuméricos y Underscore, asi también Números.
Las letras usadas en las constantes deben ser mayúsculas y las palabras separadas por Underscore, por ejemplo: EMBED_SUPPRESS_EMBED_EXCEPTION estaría permitido y EMBED_SUPPRESSEMBEDEXCEPTION no lo estaría.
Estilo en el código
PHP Código de Delimitación
Todo código PHP debe estar delimitado por los tags estándares ( los cortos no están permitidos ).
Estas delimitaciones se omiten en quellos archivos que sólo contengan código PHP.
String Literales
Cuando se le asigna un texto literal ( sin contenido de variables ) se utilizarán comillas simples.
$a = 'Texto de ejemplo';
String Literales con apóstrofes
Cuando se le asigna un texto literal con apóstrofes se utilizarán comillas dobles, este caso es principalmente en las sentencias SQL.
$sql = "SELECT `id`, `name` from `some_people` WHERE `name`='Fred' OR `name`='Susan'";
Sustitución por Variables
Cuando un texto contiene porciones que serán sustituidas por el valor de alguna variable, se toma como correcto únicamente esta dos formas:
$greeting = "Hola $nombre, bienvenido!";
$greeting = "Hola {$nombre}, bienvenido!";
Concatenación
Para concatenar Strings se utilizará el operador “.” (punto), con un espacio entre medio para mejorar la lectura.
$company = 'Zend' . ' ' . 'Technologies';
Arrays
En aquellos arrays de índices numéricos estos deberán ser números positivos, en la declaración de los valores del array se dejará un espacio en blanco luego de la coma para mejorar la lectura.
En caso que se necesiten varias líneas en la construcción del array, se identará cada una donde empezó la primera. En el caso de los arrays asociativos, se hace un quiebre de línea por cada clave y valor.
$sampleArray = array('firstKey' => 'firstValue',
'secondKey' => 'secondValue'); Clases
En la declaración de la clase el nombre deberá seguir la convención ya expresada anteriormente, debe estar precedida por una documentación conforme a PHPDocumentor, luego la declaración y desarrollo.
/**
* Documentación del bloque aquí.
*/
class SampleClass
{
// Todo el contenido de la clase aquí
// identada por cuatro espacios vacíos
}
Las funciones deberán seguir la convención de nombres, los métodos de las clases deberán ser declarados utilizando uno de los modificadores private, protected, ó public. El pasaje por referencia es el único método permitido para usar una variable externa, el llamado de una variable externa está totalmente prohibido.
A continuación un ejemplo de declaración de una variable, note que el valor de retorno no está entre paréntesis.
/**
* Documentación del bloque aquí.
*/
class Foo
{
/**
* Documentación del bloque aquí.
*/
public function bar(&$var)
{
// Todo el contenido de la función aquí
// identada por cuatro espacios vacíos
return $this->bar;
}
}
Control de flujo
En las declaraciones if/then/else deberá tener un espacio antes y después del parentesis condicional, en la misma línea se habre llave y se cierra en una línea diferente, lo mismo se aplica al elseif, a continuación un ejemplo que lo ilustra:
if ($a != 2) {
$a = 2;
} elseif ($a == 3) {
$a = 4;
} else {
$a = 7;
} En el caso de un Switch la convención es la misma, adicionando que el break tiene una identación mayor que el resto a continuación un ejemplo:
switch ($numPeople) {
case 1:
break;
default:
break;
} La opción default jamás deberá ser omitida en un Switch.
Nota: en aquel caso que dos case correspondan a un bloque de implementación, se comentará el break para diferenciarlo de un bug.
Documentación
Formato
El formato de los bloques de documentación deberán ser acorde al de PHPDocumentor, para más información visitar: phpdoc.org
Archivos
Todo archivo con Código PHP deberá incluir un Bloque de Documentación en la parte superior con estos tags de PHPDocumentor como mínimo:
/**
* Descripción corta del archivo
*
* Descripción extendida del archivo (si alguien)...
*
* LICENCIA: Algún dato sobre la licencia
*
* @copyright 2008 Zend Technologies
* @license http://framework.zend.com/license BSD License
* @version $Id:$
* @link http://framework.zend.com/package/PackageName
* @since File available since Release 1.5.0
*/
Clases
Las clases deberán incluir un Bloque de Documentación en la parte superior con estos tags de PHPDocumentor como mínimo:
/**
* Descripción corta de la clase
*
* Descripción extendida de la clase (si alguien)...
*
* @copyright 2008 Zend Technologies
* @license http://framework.zend.com/license BSD License
* @version Release: @package_version@
* @link http://framework.zend.com/package/PackageName
* @since Class available since Release 1.5.0
* @deprecated Class deprecated in Release 2.0.0
*/
Funciones
Todas las funciones y los métodos deberán tener un Bloque de Documentación conteniendo como mínimo:
- Descripción de la función
- Argumentos
- Retorno
No es necesario utilizar el tag “@access” ya que el nivel de acceso está dado por los modificadores “public”, “private”, ó “protected” usados al declarar la función.
Si algún método/función tiene expeciones utilice el tag @throws.
Fuente
Esto es un resumen para más información visitar:
Zend Framework Coding Standard for PHP
No hay comentarios:
Publicar un comentario