Fandom

Scratchpad

Estandar Documentacion PHP

215,672pages 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.

COMO DOCUMENTAR EL CODIGO PHP

Todo tiene que estar comentado antes del comienzo de la porción del código a documentar.


Cabecera del achivo

[PROPONGAN COMO DEBERIA SER LA CABECERA]

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.

  • Con que html esta relacionado cada php.
  • Que base de datos utiliza.
/**
*
* HTML: mi_template.html
* BASE DE DATOS: nombre_la_base
*
*/

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.

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)
{
   ....
}

Comentarios en Clases

Comentario Principal

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.

Comentar metodo

Los metodos se comentan igual que las funciones.

Comentar atributos

Ejemplo:

/** 
* array de destinatarios del mensaje 
* @var array destinatarios  
* @access private 
*/ 
var $to;

Comentar variables

/**
* A sample class variable
* @access private
* @var string
*/
var $sample;

Hacks

Los hacks (codigo raro) 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.

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.

REGLAS DE CODIFICACION Y LINEAMIENTO DE CODIGO EN PHP

Indentacion

La indentacion hace mas legible el codigo. Fundamental para poder trabajar en grupo sobre un mismo codigo.

1. Líneas pertenecientes a un mismo bloque de código deben estar en un mismo nivel de "indentación". 2. Un nivel de "indentación" se define como un "TAB"

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.

Estandares de nombres de variables

  • Todas las variables deben tener un nombre descriptivos y concisos (no usar ni grandes frases ni pequeñas abreviaciones para las variables).
  • Deben ser escritas en minuscula con notación "_". Excepto con las clases, donde la primera letra ha de ser mayúscula (Ej: $hola_mundo $Mi_Clase)
  • Los nombres deberan ser en singular. (Ej: $consulta y no $consultas)
  • Las variables que provienen de un formulario del html deben tener la forma $vf_nombre.

Agregado: Llamar a los campos del formulario como se llaman los campos de las tablas que estos representan (almenos para todo lo que sea ABM), no sé si es necesario usar ese tipo de nomenclatura (la que esta arriba) para todo lo que sea abm ya que es agregar cosas raras a tareas monótonas creo que con respetar el nombre de las tablas es suficiente.

Como pasar informacion entre HTML y PHP

[PREGUNTAR A FEDE] [estos son pensamientos más que aportes destruyan con cariño] Creo que es válido lo de nombrar las variables del formulario como sus representantes en las tablas, tal vez agregar lo que se pasan siempre por "post" y se capturan siempre con $_POST o $_GET, mmm evitar el uso de $_REQUEST a menos que sea necesario.

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)

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++)
{
 ...
}

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':
             // Otro codigo
      break; 
      default:
             // Código si todo falla
      break;
}

ORGANIZACION DE CARPETAS

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.
  • templates: En caso de usar un sistema de plantillas aquí guardaremos todos los archivos .html o .tpl.
  • img: Contiene las imagenes.
  • estilos: Aca van los estilos css.

REFERENCIAS

Material de Milena

Also on Fandom

Random wikia