Convenio de codificación específico para Drupal

LIBP-0124 (Libro de pautas)

Se recogen una serie de convenios de codificación específicos de Drupal, a tener en cuenta además de los generales

La comunidad Drupal ha considerado necesario la introducción de una serie de estándares que faciliten la legibilidad y estructuración del desarrollo de código para Drupal. A continuación se van a ofrecer una serie de indicaciones para la codificación php en Drupal.

Pautas

TítuloCarácter
Etiquetas de apertura y cierre en PHPObligatoria
Etiqueta de cierre al final del código de los archivosObligatoria
Sangría de lineasObligatoria
Declaración de funcionesObligatoria
Parámetros por defectoObligatoria
OperadoresObligatoria
CastingObligatoria
Longitud de líneas superior a 80 caracteresNo Recomendada
Manejo del arrayObligatoria
Llamadas al método constructor de la claseObligatoria
Concatenación de cadenasObligatoria
Punto y comaObligatoria
Nomenclatura de clases y métodosObligatoria
Nomenclatura de funcionesObligatoria
Nomenclatura de los ficherosObligatoria
Nomenclatura de los módulosObligatoria
Doxygen en DrupalRecomendada

Etiquetas de apertura y cierre en PHP

Utilizar <?php y ?> para delimitar el código PHP

En Drupal se utilizan los siguientes principios para el manejo de las etiquetas de apertura y cierre de código PHP:

  • Utilice <?php     ?> para delimitar el código PHP
  • La etiqueta de apertura simplificada, <?    ?> nunca debe usarse

Etiqueta de cierre al final del código de los archivos

No utilizar la etiqueta de cierre ?> al final del código de los archivos

Nota: a partir de Drupal 4.7, el “?>” al final del código de los archivos, es omitido deliberadamente.

Las razones para esto se pueden resumir como:

  • Elimina la posibilidad de espacios en blanco indeseados al final de los archivos, lo cual puede causar errores "header already sent" (cabecera ya enviada), problemas de validación XHTML/XML y otros problemas.
  • El delimitador de cierre al final de un archivo es opcional
  • PHP.net elimina por sí mismo el delimitador de cierre al final de sus archivos (ejemplo:prepend.inc), por lo que puede ser visto como una “buena práctica”.

Sangría de lineas

Usar una sangría de 2 espacios en blanco, sin tabulaciones

El código debe tener 2 espacios en blanco para la sangría, que no sean tabulaciones.

Declaración de funciones

Los nombres de las funciones deben incluir el nombre de grupo

Las funciones deben tener el nombre del grupo o módulo como prefijo, para evitar conflictos de nombres entre funciones de distintos módulos.

Parámetros por defecto

Listar los parámetros por defecto de las funciones

Al escribir una función que utilice valores por defecto para algunos parámetros, deben listarse estos parámetros.

Operadores

Colocar un espacio en blanco antes y después de cada operador binario

Todos los operadores binarios (operadores que están entre dos valores), como +, -, +=, !=, ==, >, etc. deben tener un espacio antes y después del operador, para facilitar la lectura.

Casting

Colocar un espacio entre el (tipo) y la $variable en una transformación

Colocar un espacio entre el (tipo) y la $variable en una transformación. Por ejemplo, (int) $mynumber

Longitud de líneas superior a 80 caracteres

Salvo las excepciones indicadas, las líneas de código no deben tener más de 80 caracteres

  • Las líneas que contengan nombres largos de funciones, definiciones de función/clase, declaraciones de variable, etc pueden superar los 80 caracteres.
  • Las condiciones de las estructuras de control pueden exceder los 80 caracteres, si es que son simples de leer y entender. Las condiciones no deben ser encapsuladas en líneas múltiples. En cambio, es una práctica recomendada dividir y preparar las condiciones por separado, lo cual también permite documentar las razones subyacentes de las condiciones

Manejo del array

Los arrays deberán estar formateados y cada elemento del array debe moverse a su propia línea si el bloque del array tiene más de 80 caracteres

Los arrays deberán estár formateados con espacios separados para cada elemento y cada operador de asignación. Si el bloque de un array tiene más de 80 caracteres, es una buena práctica para facilitar la legibilidad y mantenibilidad mover cada elemento a su propia línea.

Llamadas al método constructor de la clase

Incluir siempre los paréntesis cuando se llama a un método constructor.

Cuando se llame a un método constructor sin argumentos, deben incluirse siempre en la llamada los paréntesis del método.

Concatenación de cadenas

Utilizar un espacio entre el punto y las partes concatenadas

Emplear siempre un espacio entre el punto y las partes concatenadas de una cadena para mejorar la legibilidad. Al concatenar variables simples se pueden usar comillas dobles y agregar la variable dentro.  En otro caso, es necesario usar comillas simples. Al usar el operador de “concatenación-asignación” (‘.=’), también es necesario incluir un espacio antes y después del operador.

Punto y coma

Utilizar siempre el punto y coma (;) al final de cada línea, incluso al final de los bloques de código

El lenguaje PHP requiere puntos y comas al final de la mayoría de las líneas, pero permite ser omitidos al final de bloques de código. Los Estándares de programación de Drupal los requieren, incluso al final de bloques de código.

Nomenclatura de clases y métodos

Utilizar la nomenclatura "CamelCase" para nombrar las clases

Las clases deben ser nombradas usando la nomenclatura "CamelCase." Los métodos y propiedades de clases deben usar "lowerCamelCase"

Nomenclatura de funciones

Nombrar las funciones en minúscula, basándose en el nombre del módulo

Los nombres de las funciones estarán en minúsculas y basados en el nombre del módulo del que forman parte. Los guiones bajos se utilizarán para separar las palabras descriptivas del nombre. Después del nombre del módulo, la función debe nombrarse con el verbo y el objeto a los que hace referencia.

Nomenclatura de los ficheros

Escribir los nombres de los ficheros en minúscula

Los nombres de los ficheros deben estar en minúsculas. La excepción es para los ficheros de documentación, que deben escribirse en mayúsculas y con la terminación ".txt"

Nomenclatura de los módulos

No usar guiones bajos para el nombre de los módulos

El nombre de un módulo no debe contener guiones bajos para evitar conflictos de espacios de nombres.

Doxygen en Drupal

Usar Doxygen para generar la documentación de Drupal

Se recomienda usar la herramienta Doxygen para generar la documentación de Drupal ya que permite elegir entre una gran variedad de formatos para generar la documentación.

Contenidos relacionados

Recursos