Fandom

Scratchpad

Material de Milena

216,179pages on
this wiki
Add New Page
Discuss this page0 Share

Ad blocker interference detected!


Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.

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

Estándares generales

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

Estilo y reglas de escritura de código PHP

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:

     <?php
     $foo = 'Bob';              // Asigna el valor 'Bob' a $foo
     $bar = &$foo;              // Referencia $foo vía $bar_
     $bar = "Mi nombre es $bar";  // Modifica $bar___
     echo $foo;                 // $foo también se modifica_
     echo $bar;
     ?>

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

$foo = 25;

$bar = &$foo; // Esta es una asignación válida_

$bar = &(24 * 7); // Inválida; referencia una expresión sin nombre_

function test() {

  return 25;

}

$bar = &test(); // Invá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:

/**

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

function 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:

<tbody> </tbody>
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:

/**

  • 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
  • /

class Emilious_Sender {

 //// aqui la implementacion de la clase 

}

Declaración de funciones (elemento function)

<tbody> </tbody>
Marca Significado
@global Permite especificar el uso de variables globales dentro de la función.
@param Parámetros que

recibe la función. Formato: 

* @param tipo $nombre_var comentario
@return Valor devuelto por la función.

Formato: 

* @return tipo comentario

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

array string boolean integer float object mixed

Ejemplo:

/**

  • Verifica si una direccion de correo es correcta o no.
  • @return boolean true si la direccion es correcta
  • @param string $email direccion de correo
  • /

function check_dir_email ($email) {

  .... 

}

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

/**

  • localiza las imagenes dentro del contenido
  • @access private
  • @param string $dir_imagenes path al directorio de imagenes
  • /

function encuentra_html_imagenes($dir_imagenes) {

  .... 

}

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

/**

  • 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)
  • /

function body($body, $ctype="", $charset="") {

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:

/**

  • array de destinatarios del mensaje
  • @var array destinatarios
  • @access private
  • /

var $to;


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:

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

¿Qué hay que especificar?

  • El directorio en el que se encuentra nuestro código. phpDocumentor se encarga de recorrer los subdirectorios de forma automática
  • Opcionalmente los paquetes (@pakage) que deseamos documentar, lista de ficheros incluidos y/o excluidos y otras opciones interesantes para personalizar la documentación.
  • El directorio en el que se generará la documentación
  • 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).
  • El formato de salida de la documentación

Formatos de salida

  • HTML a través de un buen número de plantillas predefinidas (podemos definir nuestra propia plantilla de salida)
  • PDF
  • 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.

Also on Fandom

Random wikia