Guía estilo de programación.

Guía de estilo de programación

Introducción

El estilo de programación son las series de convenciones seguidas al desarrollar código fuente en un determinado lenguaje de programación. Esta guía describe las convenciones usadas para el desarrollo en PHP aunque se pueden extender perfectamente a otros lenguajes con sintaxis similar. El estilo de programación descrito en esta guía es sólo una recomendación, aunque se insta fervientemente a su utilización para garantizar que todo el código fuente generado por varias personas tenga un estilo similar con lo que se consigue que las revisiones de código entre los distintos programadores sea mucho más sencilla. Estilo genérico usado

Dentro de los estilos más genéricos de programación, se usará el estilo BSD KNF (BSD Kernel Normal Form) y se parece mucho al estilo K&R. Para más información véase la Wikipedia.

Índice de Contenido

Introducción Estilo genérico usado No se debería usar Términos usados Camel Case Lower Camel Case Upper Camel Case Palabras reservadas Indentación (sangrado) Variables Variables especiales Funciones Clases e interfaces Constantes Variables Métodos Operadores Expresiones booleanas Estructuras de control if switch for foreach while do while ? (operador ternario) Excepciones

No se debería usar

No se deberían usar los siguientes estilos de programación: El estilo Allman. El estilo Whitesmiths. El estilo GNU. La notación Húngara. La notación de nombres de elementos de varias palabras con barra baja (_). Términos usados Camel Case Es la práctica de escribir frases o palabras compuestas eliminando los espacios y poniendo en mayúscula la primera letra de cada palabra. Lower Camel Case Similar al Camel Case sólo que la primera letra de la primera palabra es también en minúscula. Por ejemplo, la frase "generar datos aleatorios" pasada a lowerCamelCase sería "generarDatosAleatorios". Upper Camel Case Similar al Camel Case siendo la primera letra de la primera palabra en

Excepciones try/catch try/catch/finally Comentarios Comentarios de aclaración del código Comentarios de documentación Conclusión

mayúscula. Por ejemplo, la frase "generar datos aleatorios" pasada a UpperCamelCase sería "GenerarDatosAleatorios". Palabras reservadas

Las palabras reservadas del lenguaje así como las construcciones que se asimilan a funciones (array(), list(), etc.) se escribirán todas en minúsculas. Indentación (sangrado) La indentación o sangrado debe ser hecha mediante tabulaciones y no se deben insertar espacios. Se recomienda que el tamaño de las tabulaciones sea de 4 espacios aunque esto queda a opción del programador. Variables

Las variables usadas en cualquier aplicación deben tener nombres que las identifiquen, es decir, nombres como "a", "b" o "c" no se deberían usar sino que deberían tener un nombre coherente con con lo que contienen. En el siguiente ejemplo los nombres de las variables son cortos por lo que no se identifica su significado:

Código Fuente

$a = 0, $b = 0, $c = 0; if($a > 10 && $b > 20 && $c > 30) { return true;

} else { return false; }

Este ejemplo debería ser:

Código Fuente

$hora = 0, $minuto = 0, $segundo = 0; if($hora > 10 && $minuto > 20 && $segundo > 30) { return true; } else { return false; }

Sólo en el caso de que la variable sea lo demasiado genérica para no tener un nombre concreto (por ejemplo el índice de un bucle) ésta se declarará con el nombre de "i" siguiendo el orden alfabético en caso de varios bucles anidados ("i", "j", "k",...). Los nombres largos de las variables se escribirán en lowerCamelCase. Variables especiales

Existen variables que no son variables de tipo simple sino que son compuestas, por ejemplo, los arrays y las estructuras. En PHP no existen estructuras ya que gracias a los arrays asociativos no son necesarias.

Para crear un array vacío, la sintaxis es la estándar:

Código Fuente

$miArray = array();

Para crear un array monodimensional, la sintaxis sería la misma que la anterior:

Código Fuente

$miArray = array(1,2,3,4,5);

Para crear un array multidimensional (o asociativo), éste se pondría en líneas separadas e indentadas una tabulación respecto al nombre de la variable que lo contiene de la siguiente forma:

Código Fuente

$miArrayMultidimensional = array( 1 => "primero", 2 => "segundo", 3 => "tercero", 4 => "cuarto" );

En caso de ser un array asociativo, para mejorar la legibilidad, se debería indentar el valor de cada entrada a la misma altura de la siguiente forma:

Código Fuente

$miArrayAsociativo = array(

API

 "Barcelona"  => 08000, "Guadalajara"  => 19000, "Leon"   => 24000, "Madrid"  => 28000, "Santa Cruz de Tenerife"=> 38000 );

$miArrayVariado = array( "primero" => 1, "segundo" => array(  "hora"   => 16,  "minuto"  => 58,  "segundo" => 16 ), "tercero" => null );

En caso de que se puedan declarar estructuras del estilo de C, serían de la siguiente forma:

Código Fuente

struct MiStruct { int valor1; int valor2; float valor3; char* nombre; }; Funciones

Los nombres de las funciones serán en lowerCamelCase. Los delimitadores del cuerpo de la función, en caso de que sean llaves ({ y }) estarán: el de apertura en la misma línea que la declaración de la

función separado por un espacio (aunque se permite que esté en la siguiente línea). La llave de cierre debe estar en una línea a parte y no debe haber más código que la propia llave de cierre. Por ejemplo:

Código Fuente

function getUserName($parametros) { // código }

En caso de que en las funciones se declare el tipo devuelto, este estará en una línea a parte encima del nombre de la función.

Código Fuente

bool getUserName(void* parametros) { // código }

En caso de que haya muchos parámetros, estos estarán en múltiples líneas indentados con tabulaciones y espacios hasta coincidir en la misma columna que el primer parámetro. Por ejemplo:

Código Fuente

function getDataFromDB($param1,         $param2,         $param3,         $param4) { // código }

Los nombres de los parámetros, igual que los nombres de las variables, deben ser nombres concretos del tipo de parámetro en cuestión. Dentro de la implementación de la función sólo debería haber un return aunque esta regla que se puede omitir siempre y cuando se mejore la legibilidad del código así como el rendimiento. Clases e interfaces

Los nombres de las clases deben estar escritos en UpperCamelCase. La indentación de las mismas debe ser de una tabulación con respecto al margen izquierdo mientras que los campos y los métodos deben estar indentados una tabulación con respecto a la clase. La implementación de los métodos deben estar indentadas con una tabulación respecto al nombre del método. El resto de estilos es similar al de las funciones normales. Dentro de las clases, los métodos deben estar separados por un retorno de carro entre sí y por un retorno de carro tanto del inicio y final de la clase como de las propiedades. Las propiedades similares pueden estar agrupadas (sin separar con retornos de carro) pero no en la misma línea, mientras que las propiedades que no tengan relación deben estar separadas por un retorno de carro igual que los métodos. Si un método o propiedad tiene documentación, se aplica la misma normal de separación.

...