Drupal - Estándares de Programación
Traducción de los estándares de programación, documentada en drupal.org
Original: http://drupal.org/coding-standards
•Versión de Drupal: Drupal 7.x , Drupal 8.x
•Audiencia: Desarrolladores y programadores
•Última modificación: 22 Junio, 2011
Nota: Los estándares de programación de Drupal se aplican a código dentro de Drupal y a sus módulos contribuídos. Éste documento está ligeramente basado en los Estándares de programación de PEAR. Los comentarios y nombres deben ser usados con la ortografía inglesa de los Estados Unidos (Ej., “color”, no “colour”).
Los estándares de programación de Drupal son independientes de versión y “siempre-actualizados”. Todo nuevo código debería seguir los actuales estándares, sin importar la versión (de núcleo). Código existente en versiones anteriores, puede ser actualizado, pero no necesariamente debe hacerse.
Especialmente para grandes bases de código (como el núcleo de Drupal), la actualización de código de una versión anterior a los actuales estándares, puede ser una tarea muy expensa.
Sin embargo, código en las actuales versiones debería seguir los actuales estándares.
Nota: No tocar las actualizaciones/limpiezas de estándares de programación en otros parches no relacionados. (Negrita: No se le pudo dar una traducción coherente. El párrafo original es: Do not squeeze coding standards updates/clean-ups into otherwise unrelated patches.) Solamente tocar las líneas de código que son realmente relevantes. Para actualizar código existente para los actuales estándares, siempre crear problemas y parches separados y dedicados.
También tenga en cuenta:
• El módulo "Coder" proporciona un modo automatizado de control para el cumplimiento de estándares de programación y
• El módulo “Grammar Parser” proporciona un modo automatizado de reescritura de archivos de código en cumplimiento con los estándares de programación.
Contenidos de esta Página
• Sangrías y Espacios en blanco
• Operadores
• Transformaciones
• Estructuras de control
• Longitud de línea y encapsulamiento(wrapping)
• Llamadas de función
• Declaraciones de función
• Llamadas a la Clase Constructora
• Arreglos
• Comillas
• Concatenaciones de cadenas
• Comentarios
• Incluyendo código
• Etiquetas de código PHP
• Punto y coma
• URLs de ejemplo
• Convenciones de nombre (Funciones, Constantes, Variables Globales, Clases, Archivos)
• Módulo “Helper” (de ayuda)
Sangrías y Espacios en blanco
Usar una sangría de 2 espacios, sin etiquetas.
Las líneas no deben tener espacios en blanco al final.
Los archivos deben tener el formato \n como final de línea (finales de línea de Unix), no \r\n (finales de línea de Windows).
Todos los archivos de texto deben terminar en un solo salto de línea (\n). Esto evita el parche de alerta “\ No existen saltos de línea al final del archivo” y hace a los parches más legibles ya que se hace claro que está siendo cambiado cuando se agregan líneas al final del archivo.(Negrita: No se le pudo dar una traducción coherente. El párrafo original es: This avoids the verbose "\ No newline at end of file" patch warning and makes patches easier to read since it's clearer what is being changed when lines are added to the end of a file. )
Operadores
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. Por ejemplo, una asignación debe tener el formato $foo = $bar; en vez de $foo=$bar;. Los operadores unarios (operadores que operan sobre un solo valor), como ++, no deben tener espacios entre el operador y la variable o número que se utiliza.
Transformaciones
Colocar un espacio en el (tipo) y la $variable en una transformación:
<?php
(int) $minumero
?>Estructuras de control
Las estructuras de control incluyen: if, for,while,switch,etc. Aquí se presenta un ejemplo de la sentencia if, ya que es el más complicado de ellos:
<?php
if (condicion1 || condicion2) {
//accion1;
}
elseif (condicion3 && condicion4) {
//accion2;
}
else {
accionpordefecto;
}
?>Las sentencias de control deben tener un espacio entre la palabra clave (keyword) y el paréntesis de apertura, para distinguirlas de las llamadas de función.
Se le recomienda siempre utilizar paréntesis de llave, incluso en situaciones en que son técnicamente opcionales. Tenerlos incrementa la legibilidad y disminuye la probabilidad de introducir errores lógicos cuando nuevas líneas son agregadas.
Para la sentencia switch:
<?php
switch (condition) {
case 1:
//acción 1;
break;
case
2:
//acción 2;
break;
default:
//Acción por Defecto;
}
?>Para la sentencia do-while:
<?php
do {
acciones;
} while ($condicion);
?>Longitud de línea y encapsulamiento (wrapping)
Las siguientes reglas se aplican al código. Ver "Doxygen y convenciones de formato de comentarios" para las normas relativas a los comentarios.
• En general, todas las líneas de código no deben ser más largas 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.
<?php
if ($something['with']['something']['else']['in']['here'] == mymodule_check_something($whatever['else'])) {
...
}
if (isset($something['what']['ever']) && $something['what']['ever'] > $infinite && user_access('galaxy')) {
...
}
//Las condiciones no obvias de baja complejidad, también son aceptables, pero deben estar //Siempre documentadas, explicando por qué un chequeo o análisis en particular se lleva a cabo.
if (preg_match('@(/|\\)(\.\.|~)@', $target) && strpos($target_dir, $repository) !== 0) {
return FALSE;
}
?>• Las condiciones no deben ser encapsuladas en líneas múltiples.
• Las condiciones de las estructura de control no deben intentar ganar el premio a La Condición más Compacta en la Menor Cantidad de Líneas de Código™.
<?php
// NO HAGA ESTO!
if ((isset($key) && !empty($user->uid) && $key == $user->uid) || (isset($user->cache) ? $user->cache : '') == ip_address() || isset($value) && $value >= time())) {
...
}
?>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:
<?php
//La llave (key) es solo válida si coincide con el ID del usuario, de lo contrario otros
//usuarios pueden acceder a las cosas de cualqueir usuario.
$is_valid_user = (isset($key) && !empty($user->uid) && $key == $user->uid);
//La IP debe coincidir con la caché para evitar la suplantación de sesión.
$is_valid_query = (isset($user->cache) ? $user->cache == ip_address() : FALSE);
//Alternativamente, si el parámetro de la solicitud de consulta está en el futuro, entonces
//es siempre válido, porque la galaxia pude implosionar y colapsar de todos modos.
$is_valid_query = $is_valid_cache || (isset($value) && $value >= time());
if (
$is_valid_user || $is_valid_query) {
...
}
?>Nota: Este ejemplo puede ser aún un poco denso o complejo. Siempre considere y decida por su propia cuenta, si la gente no está familiarizada con su código deberá ser capaz de darle sentido lógico.
Llamados de función
Las funciones deben ser llamadas sin espacios entre el nombre de la función, el paréntesis de apertura, y el primer parámetro; con espacios entre las comas y cada parámetro, y sin espacios entre el último parámetro, el paréntesis de cierre, y el punto y coma. Aquí hay un ejemplo:
<?php
$var = foo($bar, $baz, $quux);
?>Como se muestra arriba, debe haber un espacio en cada lado del signo igual usado para asignar el valor de retorno de una función a una variable. En el caso de un bloque de asignaciones relacionadas, se pueden insertar más espacios para mejorar la legibilidad:
<?php
$short = foo($bar);
$long_variable = foo($baz);
?>Declaraciones de función
<?php
function funstuff_system($field) {
$system[ "description" ] = t("This module inserts funny text into posts randomly.");
return $system[ $field ];
}
?>Los argumentos con valores por defecto van al final de la lista de argumentos. Siempre intente retornar un valor significativo de una función si es apropiado. (No está clara la traducción: Always attempt to return a meaningful value from a function if one is appropriate)
Llamadas a la clase constructora
Cuando se llame a una clase constructora sin argumentos, siempre incluya los paréntesis:
<?php
$foo = new MiNombreDeClase ();
?>Esto es para mantener la consistencia con los constructores que tienen argumentos:
<?php
$foo = new MiNombreDeClase ($arg1, $arg2);
?>Tenga en cuenta que si el nombre de la clase es una variable, la variable primero deberá ser evaluada para obtener el nombre de la clase, y después el constructor deberá ser llamado. Use la misma sintaxis:
<?php
$bar = 'MiNombreDeClase';
$foo = new $bar();
$foo = new $bar($arg1, $arg2);
?>Arreglos
Los arreglos deben tener en su formato un espacio separando cada elemento (después de la coma), y espacios alrededor del operador “=>” (asociación de llave), si es el caso:
<?php
$some_array = array('hello', 'world', 'foo' => 'bar');
?>Tome en cuenta que si la línea que declara un arreglo se extiende por más de 80 caracteres (a menudo en el caso de la declaración de formularios y menús), cada elemento debe dividirse en su propia línea, y tener una sangría de un nivel:
<?php
$form['title'] = array(
'#type' => 'textfield',
'#title' => t('Title'),
'#size' => 60,
'#maxlength' => 128,
'#description' => t('The title of your node.'),
);
?>Tomar en cuenta la coma en el final del último elemento del arreglo. Esto no es un error! Ésta ayuda a prevenir errores de análisis sintáctico, si otro elemento es colocado al final de la lista más tarde.
Comillas
Drupal no tiene un estándar fuerte para el uso de comillas simples vs. comillas dobles. Mientras sea posible, se debe mantener la consistencia en cada módulo, y respetar el estilo personal de otros desarrolladores.
Con este aviso en mente: las cadenas de comillas simples son conocidas por ser más rápidas, debido a que el analizador o intérprete no tiene que buscar en las variables “en línea”.
Su uso se recomienda, a excepción de dos casos.
1. Uso en variables “en línea”, Ejemplo:
<?php
<h2>$header</h2>
?>.
2. Cadenas traducidas donde se puede evitar el escape de comillas simples encerrando la cadena en comillas dobles. Una de estas cadenas podría ser: "He's a good person." Ésta sería 'He\'s a good person.' con comillas simples. Tal escape no puede ser manejado adecuadamente por los generadores de archivos.pot para la traducción de texto, y además es un poco difícil de leer.
Concatenación de cadenas
Siempre use un espacio entre el punto y las partes concatenadas para mejorar la legibilidad.
<?php
$string
= 'Foo' . $bar;
$string = $bar . 'foo';
$string = bar() . 'foo';
$string = 'foo' . 'bar';
?>Cuando concatena variables simples, puede usar comillas dobles y agregar la variable dentro, en otro caso, use comillas simples.
<?php
$string = "Foo $bar";
?>Cuando use el operador de “concatenación-asignación” (‘.=’), use un espacio en cada lado como en el operador de asignación:
<?php
$string .= 'Foo';
$string .= $bar;
$string .= baz();
?>Comentarios
Los estándares de los comentarios son discutidos de forma separada en la página:
"Doxygen y convenciones de formato de comentarios”
Incluyendo código
Donde sea que esté incondicionalmente incluyendo un archivo de clase, utilice: require_once(). Donde sea que esté condicionalmente incluyendo un archivo de clase (por ejemplo métodos de fábrica “factory method”), utilice include_once(). Cualquiera de éstas, asegurará que los archivos de clase sean incluidos una sola vez. Ellas comparten la misma lista de archivos, por lo cual no necesita preocuparse por mezclarlos: Un archivo incluido con require_once() no será incluido de nuevo con include_once().
Aviso: include_once() y require_once() son declaraciones, no funciones. No necesita utilizar paréntesis alrededor del nombre del archivo para ser incluido. Cuando se incluye código del mismo directorio o de un sub-directorio, empiece la ruta del archive con “.”:
include_once ./includes/mymodule_formatting.inc
En Drupal 7.x y versions posteriors use DRUPAL_ROOT:
require_once DRUPAL_ROOT . '/' . variable_get('cache_inc', 'includes/cache.inc');
Etiquetas de código PHP
Siempre utilice <?php ?> para delimitar el código PHP, no de la forma reducida ?>. Esto es requerido para la conformidad (aceptación) de Drupal y es también la manera más portable de incluir código PHP en diferentes sistemas operativos y configuraciones.
Note que a partir de Drupal 4.7, el “?>” al final del código de los archivos, es omitido deliberadamente. Esto considera módulos y archivos incluidos. Las razones para esto se pueden resumir como:
• Removerlo 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”.
Punto y coma
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. En particular para una línea de bloques PHP:
<?php
print $tax;
?>-- SÍ
<?php
print $tax
?>-- NO
URLs de ejemplo
Usar “example.com” para todas las URLs de ejemplo, por medio de 2606 RFC (Request for Comments).
Convenciones de nombre
Funciones y variables
Las funciones y variables deben ser nombradas usando minúsculas, y las palabras deben ser separadas utilizando un guión bajo. Las funciones deben tener además el nombre del grupo/módulo como prefijo, para evitar el conflicto de nombres entre los módulos.
Variables persistentes
Las variables persistentes (variables/configuraciones definidas usando las funciones de Drupal variable_get()/ variable_set()) deben ser nombradas usando minúsculas y las palabras deben ser separadas utilizando un guión bajo. Deben usar el nombre del grupo/módulo como prefijo, para evitar el conflicto de nombres entre los módulos.
Constantes
Las constantes deben estar siempre en mayúsculas, con guiones bajos para separar las palabras. Esto incluye a las constantes PHP pre-definidas como TRUE, FALSE y NULL. Los nombres de las constantes definidas en los módulos deben también tener una mayúscula como prefijo del módulo por el cual son definidas.(Negrita: No se le pudo dar una traducción coherente. El párrafo original es: Module-defined constant names should also be prefixed by an uppercase spelling of the module they are defined by.)
Variables Globales
Si necesita definir variables globales, sus nombres deben empezar con un guión bajo simple seguido de un nombre de módulo/tema y otro guión bajo.
Clases
Las clases deben ser nombradas usando "CamelCase." Por ejemplo:
<?php
abstract class DatabaseConnection extends PDO {
?>Los métodos y propiedades de clases deben usar "lowerCamelCase":
<?php
public $lastStatement;
?>El uso de propiedades y métodos de clases privadas debe ser omitido: use protected/instead, con lo cual otra clase podría extender su clase y cambiar el método, si es necesario. (Negrita: No se le pudo dar una traducción coherente. El párrafo original es: The use of private class methods and properties should be avoided -- use protectedinstead, so that another class could extend your class and change the method if necessary.) Los métodos y propiedades protegidas (Protected) (y públicas) no deben usar un guión bajo como prefijo, como era común en la era de PHP 4. Para más información sobre la clase y las normas OO, ver la cobertura más detallada .
Nombre de archivos
Todos los archivos de documentación deben tener en el nombre la extensión “.txt” para hacer más fácil su lectura en sistemas Windows. Además los nombres para este tipo de archivos deben ser todo en mayúsculas. Ejemplos: README.txt, INSTALL.txt, TODO.txt, CHANGELOG.txt etc.
Módulo de ayuda
Hay un modulo contribuído para ayudar en la revisión de código. Para usar este módulo debe completar los siguientes pasos:
• Instalar el módulo Coder .
• Hacer clic en el link "Code Review"(“revisión de código”) en su menú de navegación.
• Ir a "Select Specific Modules"(“Seleccionar Módulos Específicos”).
• Seleccionar el módulo que quiere revisar, y haga clic en el botón "Submit”(“Aceptar”).
Como una alternativa a partir de la Revisión de Código desde el link del menú de navegación, puede también hacer una revisión del código de un módulo en particular, haciendo clic en el link en la pantalla de administración de Módulos.
El módulo Coder también viene con un script de línea de comandos llamado "Coder Format", el cual no sólo revisará sus archivos para el cumplimiento de estándares, sino que también los arregla. ¡Úselo con cuidado!
Añadir nuevo comentario