Buenas prácticas de codificación


Tabla de contenidos:

Para todo en la vida existen las buenas prácticas, estas son la acumulación de experiencias que nos permitirá comprender y agilizar los procesos que llevemos a acabo, son fundamentales para el trabajo en equipo ya que por medio de ellas hablaremos el mismo idioma, en cuanto a organización se refiere.

Desde Drupal 6 se emplean una serie de normas o pautas para formatear el código fuente de una manera común para todos lo desarrolladores. Por eso Drupal no s brinda los siguientes estándares para que podamos guiarnos.

Una de las cosas fundamentales a tener en cuenta es que el idioma nativo que utiliza la comunidad de Drupal es el ingles para la documentación oficial y documentación de nuestro código fuente.

Existe un módulo llamado codre que permitirá comprobar si el código de nuestros módulos cumple con los estándares de codificación de Drupal, luego veremos un poco de esto.

Estándares de codificación de Drupal

Identación

Para que el código sea más legible podemos insertar espacios en blanco. En Drupal se usa indentar con 2 espacios, y nunca con tabulaciones, también debes tener presente que nunca se debe dejar espacios en blanco al final de cada línea, si deseas continuar en la siguiente línea simplemente presiones la tecla <ENTER>.

Estructuras de control

Las estructuras de control deben tener el siguiente formato:

if (condición_1 || condición_2) {
  acción_1;
}
elseif (condición_3 && condición_4) {
  acción_2;
}
else {
  acción predeterminada;
}
  • Como se puede apreciar, hay un espacio entre las palabras reservadas (if, while, for, else, etc) y el parentesis de apertura
  • Entre el parentesis de cierre y la llave de apertura { también tiene su correspondiente espacio
  • Siempre debes usar las llaves de apertura y cierre
  • Las estructuras else y elseif deben ir en líneas aparte, debajo del cierre de la estructura, en este caso debajo de la llave de cierre

 Ejemplo de switch:

switch (condición) {
  caso_1:
    acción_1;
    break;

  caso_2:
    acción_2;
    break;

  default:
    acción predeterminada;
}

Ejemplo de do:

do {
  acción;
} while ($condición);

Etiquetas de apertura y cierre de PHP

Al escribir código  PHP, debemos utilizar las etiquetas de apertura <?php y la etiqueta de cierre  ?>, en los archivos .module y .inc puedes omitir la etiqueta de cierre siempre y cuando estes trabajando solo con php, omitir la etiqueta de cierre evita que queden líneas en blanco lo que podría dar como resultado un error  típico "Cannot modify header inforamticon - header already sent by ..".

Recuerda que cuando trabajas con PHP puro, puedes evitar la etiqueta de cierre, pero embebes dentro de HTML debes utilizar la etiqueta de apertura de PHP <?php y la etiqueta de cierre de PHP ?>.

Uso de comillas

Podés utilizar comillas simples ('texto')  o comillas dobles ("texto") para delimitar las cadenas, recuerda que las comillas dobles permiten interpretar el valor de una variable, entonces para "<h1>$title</h1>", el resultado sería el valor de la variable $title. 

Uso de punto y coma

En Drupal siempre debes finalizar las líneas de código PHP con el punto y coma.

Operadores

Todos los operadores binarios (operadores que se utilizan entre dos valores), deben tener un espacio de separación entre ellos, esto aplica a operadores como  +, -, *, /, =, ==, !=, <, >, ., .=, +=, +-, etc.

Ejemplo de una asignación:

$numero = 3;

Los operadores unarios como el ++ y el -- no deben tener separación

Ejemplo de operador unario

$numero++;

 

Funciones

Los nombres de las funciones deben estar escritas en minúsculas, y las palabras deparadas por un guión bajo. Siempre debes escribir como prefijo el nombre del módulo, tema, etc para evitar así generar nombres duplicados.

Entre el nombre de la función y el parentesis de inicio de los argumentos no debes dejar espacios, cada argumento debe estar separados por una coma y luego un espacio. Si debes colocar un espacio entre el cierre del parentesis y la apertura de la llave que contiene el bloque de código.

Ejemplo:

function forum_help($path, $arg) {
   bloque de código
  ....
}

La llamada a la función tiene las mismas reglas que la declaración, ejemplo:

$var = foo($bar, $baz, $quux);

Cuando asignés una serie de funciones, podes dejar varios espacios para darle una organización visual, aquí no hay restricciones, ejemplo:

$bar = 'NombreDeMiClase';
$foo = new $bar();
$foo = new $bar($arg1, $arg2);

Arreglos

Dentro del arreglo o matriz, tenes que separar con un espacio (luego de la coma) los valores. El operador => debe separarse por un espacio a ambos lados. Si has leido los estandar de codificación de ZendFramework vas a ver que hay muchas similitudes.

Cuando superes los 80 caracteres en la declaración del arreglo, debes escribir cada uno de los elementos en una única línea, la identación debe tener 2 espacios. 

Ejemplos:

$some_array = array('hello', 'world', 'foo' => 'bar');
$form['title'] = array(
  '#type' => 'textfield',
  '#title' => t('Title'),
  '#size' => 60,
  '#maxlength' => 128,
  '#description' => t('Título del nodo.'),
);

Constantes

Siempre debes escribir en mayúsculas los nombres de las constantes, si estas se componen de varias palabras entonces puedes separarlas con guiones bajos, otra cosa importante al igual que en las funciones debes colocar de prefijo el nombre dle módulo o tema a donde pertenece, el objetivo es evitar crear nombres duplicados, recuerda que el prefijo debes estar también en mayúsculas.

<?php
/**
 *  The current system version.
 */
define('VERSION', '7.10');

/**
*  Minimum supported version of PHP.
*/
define('DRUPAL_MINIMUM_PHP', '5.2.4');
?>

Variables globales

Si necesitamos definir variables globales tenes que comenzar con el nombre con un guión bajo seguido por el nombre del módulo ó tema y otro guión bajo antes del nombre de la variable.

global $_forum_pagina_foros;

Nombre de los módulos

Por norma general, el nombre de un módulo nunca debe incluir guiones bajos, aunque este se componga de varias palabras.  Es muy provable que encuentres nombre de módulos con guiones bajos, ya que esta no es una regla obligatoria.

Ejemplo:

mimodulo

Nombre de los archivos

Siempre debes escribir los nombres de archivos en minúsculas, salvo los nombre de archivos que contengan documentación como por ejemplo, README.txt, INSTALL.txt, etc.

Ejemplo de URLs

Por convención, siempre que vayas a utilizar una URL como ejemplo, esta debe ser "example.com". Esto es según RFC 2606.

Idioma 

Drupal utiliza el idioma inglés como base para todo el sistema, por este motivo debes escribir la documentación (módulos, temas, archivos, nombre de funciones, variables, etc.) en este idioma, también las cadenas de texto que ve el visitante del sitio ya que la traducción del mismo se realiza mediante la función t(), luego hablaremos de ella. 

Comentar el código

Debemos diferenciar los comentarios que utilizamos para aclarar determinados bloques de código, ya que estos los podemos colocar donde creamos que sea necesario, de los los comentarios de documentación que son los que se escriben al principio del archivo, o antes de declarar alguna función, estos últimos son sumamente importantes ya que por medio de una API se genera la documentación de ayuda desde las etiquetas que se emplean.

En el tipo de documentación que utilizamos para aclarar algún bloque de código se utiliza las etiquetas de apertura /* y de cierre */, entre ellas podemos colocar varias líneas de nuestro comentario, o podríamos utilizar las etiquegas // para un comentario de una simple línea.

// comentario de una simple línea


/**
  *  Comentario de varias
  *  líneas de texto
  */

function system_init() {

  // Otro comentario de una sola línea
  ...   mi bloque de código
}

 

 

 

Grupo: 
Valoración: 
0
Sin votos (todavía)

Añadir nuevo comentario

Plain text

  • No se permiten etiquetas HTML.
  • Las direcciones de las páginas web y las de correo se convierten en enlaces automáticamente.
  • Saltos automáticos de líneas y de párrafos.
CAPTCHA
Esta pregunta es para comprobar si usted es un visitante humano y prevenir envíos de spam automatizado.
4 + 12 =
Resuelva este simple problema matemático y escriba la solución; por ejemplo: Para 1+3, escriba 4.