C1-Reglas de codificacin y lineamientos de

cdigo PHP

Siguiendo las sencillas reglas de esta gua permite una mejor

organizacin y productividad en la programacin de proyectos en equipos
o en solitario. Gran parte de estas reglas estn basadas en las guas de
estilo de grandes proyectos libres, como phpBB.
Estndares generales
Tabs o Espacios.
En el contenido dentro de corchetes, siempre se identar este contenido
con tabs. Cualquier editor decente puede configurarse para poner tabs
en vez de espacios en la identacin (Dreamweaver, Aptana, Eclipse, etc).

Aptana es uno de los editores que dan esa posiblidad.

Cabecera del archivo
Siempre es importante que todos los archivos .php inicien con una
cabecera especfica que indique informacin de la versin, autor de los
ltimos cambios, etc. Es de cada equipo decidir si se quiere o no agregar
ms datos.
/**
*
* @Control de presentacin de los weblogs. "weblog.php"
* @versin: 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 declaracin,
explicando que hacen. Ningn programador debera tener que analizar el
cdigo de una funcin para conocer su utilidad. Tanto el nombre como el
comentario que acompae a la funcin deben bastar para ello.
Clases
Las clases sern colocadas en un archivo .php aparte, donde slo se
colocar el cdigo de la clase. El nombre del archivo ser el mismo del
de la clase y siempre empezar en mayscula. 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 declaracin de la clase explicando su utilidad.
Hacks
Los hacks que sea necesario colocar en el cdigo deben, como las
clases o funciones, ser comentados y en lo posible animar a otros
programadores a reemplazarlos o mejorarlos por soluciones mejores.
Ubicacin de archivos
En proyectos web o aplicaciones, generalmente se tendrn las siguientes
carpetas:
/ Carpeta raiz: Aqu irn 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 mdulos o de libreras de funciones.
db: En caso de tener la posibilidad de usar varias bases de datos, aqu
colocaremos los .php que manejen esas caractersticas multicapa para
cada sistema de datos soportado.
templates: En caso de usar un sistema de plantillas (Como smarty o el
de phpBB), aqu guardaremos todos los archivos .tpl.
Estilo y reglas de escritura de cdigo PHP
Nombres de variables
Por ms que parezca lo ms "cool", se recomienda no adoptar
la notacin hungara en el cdigo. Esta es aquella donde colocamos el
tipo de datos antes del nombre de variable: strNombre para un string. En
lo posible NO la usen, muchos grandes proyectos creen firmemente que
es una de las tecnicas de ofuscacin de codigo ms ampliamente usadas
en la actualidad.Los nombres deben ser descriptivos y concisos. No usar
ni grandes frases ni pequeas abreviaciones para las variables. Siempre
es mejor saber que hace una variable con slo conocer su nombre. Esto
aplica para los nombres de variables, funciones, argumentos de
funciones y clases.Todos los nombres deben estar en minscula
(Excepto con las clases, donde la primera letra ha de ser mayscula). En
caso de usar ms de una palabra, sta ser separada por un signo de
underscore "_".En las funciones, es importante que el nombre denote su
funcin inmediatamente. Cosas como imprimir_datos estn bien, pero
estara mejorimprimir_datos_usuario. De igual manera, en
los argumentos de las funciones queremos saber inmediatamente que
estamos usando. Es mejorcrear_usuario($nick, $email) que crear($n,
$e).La filosofa es sencilla. No daes la legibilidad del codigo por pereza.
Por supuesto, aplica el sentido comun y no crees funciones de ms de 4
palabras.
Siempre incluir corchetes
Es sencillo, si ibas a hacer esto:
if($cosa) funcion();
Mejor haz esto
if ($cosa)
{
funcion();
}
No gastas mucho tiempo adicional y ganas muchsimo en legibilidad.
Corchetes o llaves. Donde colocarlas
Aunque esto sea motivo de peleas constantes en los equipos de trabajo,
lo mejor es seguir el camino que permita mayor claridad en el desarrollo.
Para ponerlo en pocas palabras, todos los corchetes van en una lnea
propia.
if (algo)
{
for (iteracion)
{
//cdigo
}
}
while (condicin)
{
funcion();
}

Poner espacios entre signos

Otra cosa simple. Si tienes un signo binario, pon espacios a ambos
lados. Tienes un signo unario, pon espacios a uno de sus lados. O en
trminos ms simples, programa como si escribieras (bien) en espaol.
Es algo muy sencillo que puede ayudar de gran manera en la lectura del
cdigo.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
Puedes ser un programador hardcore, pero, En serio te sabes la
precedencia de operadores en PHP? Como creemos que no, lo mejor es
siempre usar parntesis para estar seguro. Bsicamente, la idea es no
dejar operaciones complejas a freaks matematicos y estar seguros que
nuestros compaeros en el equipo con menos habilidad comprendan
todo sin problemas:
//Qu carajos 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 ms 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 razn siempre has de
usar comillas simples a menosque necesites hacer la interpolacin de
variables que permiten las dobles. Es difcil acostumbrarse porque ocurre
slo en PHP (Y algunos otros ms malignos, Perl4Life) 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 sintete con libertad de romper sta regla cuando sea en pro de
mejorar la lectura del cdigo.
Nmeros dentro del cdigo
A veces ponemos nmeros especiales dentro de nuestro cdigo para
situaciones especiales. NO LO HAGAS. Si necesitas poner un nmero
especial, convirtelo en constante y entonces implemntalo. Ejemplo:
define('ARTICULOS_PORTADA', 10);
for ($i = 0; $i < ARTICULOS_PORTADA; $i++)
{

Operadores unarios de suma y resta.

Es sencillo, salos en una sola lnea 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 lnea

salas slo para hacer cosas simples. En lo posible siempre utiliza if
//Slo 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 slo usa est opcin cuando no tengas el control o no ests seguro
que valor pueda tener la variable (Como en variables que llegan por
parmetro o por GET, etc)
Instruccin switch
Esta es una de las cosas ms feas de los lenguajes con estilo de C.
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 aos
break;

default:
// Cdigo si todo falla
break;
}
No obligatorio, pero recomendado. La programacin de proyectos PHP
en grupo se hace mucho ms efectiva aplicando estas reglas. Si deseas
ampliar esta informacin y conocer otras guas como reglas para efectuar
consultas SQL, para crear plantillas de diseo o para otros casos
avanzados, te invitamos a leer las Coding Guidelines de phpBB.