(*) Basado en la charla “Buenas Prácticas de Programación en Drupal”, por Fernando P. García.
Drupal es un Administrador de Contenido de Software Libre. En su desarrollo y mantenimiento participan diseñadores, programadores y colaboradores en general, de todas partes del mundo. Para poder lograr que todos los aportes se den en forma ordenada y minimizar los problemas cuando alguien debe tomar el proyecto de otro para corregirlo o mejorarlo, se ha definido ciertas buenas prácticas, que toda la comunidad de Drupal sigue con el fin de facilitar las cosas. Estas incluyen obviamente la forma en que se programa en PHP (el lenguaje sobre el cual está construido Drupal), pero también cómo se debe utilizar otras herramientas como jQuery, Bases de Datos, estilos (CSS), control de versiones, documentación, etc.
En este caso vamos a enfocarnos en algunas buenas prácticas que utiliza la comunidad de Drupal para programar en PHP, y que pueden resultar útiles para equipos de programación en general, que tengan que estar desarrollando, compartiendo, depurando y probando código entre ellos.
Comentarios
Una buena práctica es seguir el estándar de Doxygen para los comentarios.
Doxygen -acrónimo de dox(document) gen(generator)- es un generador de documentación para código fuente. En PHP, como en otros lenguajes de programación, los comentarios se ingresan dentro de las combinaciones de caracteres /* (para abrir el comentario) y */ (para cerrarlo) cuando el comentario abarca más de una línea, o bien con // para indicar que en el salto de línea termina el comentario.
No hay ninguna definición dentro de la sintaxis original de PHP que indique lo que el programador puede agregar dentro de un comentario, sin embargo al adherirse a los parámetros que define Doxygen, es posible utilizar luego toda la información que se ha añadido en estos comentarios como base para generar la documentación del programa que se está desarrollando.
Aún si no se va a utilizar Doxygen para generar una base de documentación, seguir las pautas que sugiere permite que los programadores mantengan consistencia en la manera que agregan comentarios a sus programas.
A continuación dos ejemplos de comentarios del código de Drupal, que muestran el uso de Doxigen:
// $Id: index.php,v 1.94 2007/12/26 08:46:48 dries Exp $
/**
* @file
* The PHP page that serves all page requests on a Drupal installation.
*
* The routines here dispatch control to the appropriate handler, which then
* prints the appropriate page.
*
* All Drupal code is released under the GNU General Public License.
* See COPYRIGHT.txt and LICENSE.txt.
*/
Para más detalles sobre Doxygen y se puede visitar el sitio web del autor, Dimitri van Heesch: http://www.stack.nl/~dimitri/doxygen/
Indentación
Casi todos los programadores entienden la importancia de indentar el código, y lo aplican relativamente bien. Sin embargo en Drupal se ha generalizado el uso de dos espacios como norma para las indentaciones. No se utiliza el Tabulador, pues la longitud de las tabulaciones puede diferir de editor en editor, y esto puede provocar que el código se vea desordenado.
Este es un ejemplo de código indentado a dos espacios:
function drupal_init_path() {
if (!empty($_GET['q'])) {
$_GET['q'] = drupal_get_normal_path(trim($_GET['q'], '/'));
}
else {
$_GET['q'] = drupal_get_normal_path(variable_get('site_frontpage', 'node'));
}
}
Separación
Se siguen ciertas pautas para separar los diferentes elementos en una línea de código; por ejemplo, dejando espacios antes y después de los operadores (” = “, ” != “, ” && “, ” => “, ” : “, etc), o luego de la coma (“, “) cuando se listan parámetros; e igualmente, luego de usar estructuras de control como if, else, foreach, switch, etc., y antes de abrir una llave de agrupación (” {“). A veces se acostumbra hacer una separación por medio de líneas vacías entre la declaración de la función y sus variables, el cuerpo, y el retorno.
Este es un ejemplo donde se puede ver el uso de espacios para mantener el orden:
function image_get_toolkit() {
static $toolkit;
if (!$toolkit) {
$toolkit = variable_get('image_toolkit', 'gd');
$toolkit_file = './includes/image.'. $toolkit .'.inc';
if (isset($toolkit) && file_exists($toolkit_file)) {
include_once $toolkit_file;
}
elseif (!image_gd_check_settings()) {
$toolkit = FALSE;
}
}
return $toolkit;
}
Agrupación
El uso de llaves es obligatorio para agrupar secciones de código que se ejecutan dentro de una estructura de control. La llave se abre en la misma línea donde se declara la condición, y se cierra luego de la última línea de código de ese bloque lógico. Aunque no es necesario utilizarlas en casos que incluyen únicamente una línea, se recomienda mantener la norma pues esta práctica produce código mucho más ordenado y fácil de leer.
Por ejemplo, la siguiente función
function db_field_names($fields) {
$ret = array();
foreach ($fields as $field) {
if (is_array($field)) {
$ret[] = $field[0];
}
else {
$ret[] = $field;
}
}
return $ret;
}
podría escribirse como
function db_field_names($fields) {
$ret = array();
foreach ($fields as $field)
if (is_array($field)) $ret[] = $field[0]; else $ret[] = $field;
return $ret;
}
sin embargo, aunque la sintaxis es correcta, y se ejecuta exactamente igual que en la forma de arriba, se complica su interpretación. Si se piensa en intentar depurar archivos de cientos de líneas escritas sin agrupar unidades lógicas, el trabajo se vuelve mucho más complicado.
En resumen, la aplicación de estas sencillas reglas puede ayudar a que los equipos de programación tengan una mejor comunicación entre ellos, disminuye el tiempo de adaptación cuando se debe tomar el código de otros, agiliza los procesos de depuración, estandariza nuestros esquemas mentales y le añade profesionalismo al trabajo final.
Para más información sobre este tema, se recomienda consultar la documentación oficial de Drupal (http://drupal.org/coding-standards), la guía de buenas prácticas de PHP (http://www.odi.ch/prog/design/php/guide.php) y el siguiente artículo en Nettuts+: http://net.tutsplus.com/tutorials/php/30-php-best-practices-for-beginners/.
