mirror of
https://github.com/moodle/moodle.git
synced 2025-02-23 19:44:19 +01:00
345 lines
22 KiB
HTML
345 lines
22 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>Moodle Docs: manual de estilo del código</title>
|
|
<link rel="stylesheet" href="docstyles.css" type="TEXT/CSS" />
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
</head>
|
|
<body>
|
|
<h1>Manual de Estilo del Código</h1>
|
|
<p class="normaltext">Cualquier proyecto colaborativo necesita que la consistencia
|
|
y la estabilidad sean fuertes.</p>
|
|
<p class="normaltext">Este manual de estilo ha sido escrito para conseguir que
|
|
todo el código de Moodle cumpla estas características. Es cierto
|
|
que la parte más antigua del código no cumple lo aquí especificado
|
|
en algunos casos, pero esto será solucionado gradualmente.
|
|
Todo el código
|
|
nuevo definitivamente deberá adherirse a estos estándares
|
|
de la forma más exacta posible.</p>
|
|
<h2>Reglas Generales</h2>
|
|
<ol class="normaltext">
|
|
<li class="spaced">Todos los archivos con código deberían utilizar la extensión
|
|
.php.</li>
|
|
<li class="spaced">Todas las plantillas deberían utilizar la extensión .html.</li>
|
|
<li class="spaced">Todos los archivos de texto deberían utilizar el formato
|
|
de texto Unix (la mayoría de los editores de texto tienen esto como una opción).</li>
|
|
<li class="spaced">Todas las etiquetas php deben ser 'completas' como <font color="#339900"><?php
|
|
?></font> ... no 'reducidas' como <font color="#339900"><?
|
|
?></font>.
|
|
</li>
|
|
<li class="spaced">Todos los avisos de copyright deben ser mantenidos. Puede
|
|
incluir los suyos propios si resulta necesario.</li>
|
|
<li class="spaced">Todos los archivos deben incluir el archivo principal config.php.</li>
|
|
<li class="spaced">Cada archivo debería comprobar que el usuario está autenticado
|
|
correctamente, utilizando las funciones require_login() y
|
|
isadmin(),
|
|
isteacher(),
|
|
iscreator()
|
|
o isstudent().</li>
|
|
<li class="spaced">Todos los accesos a la base de datos deberían utilizar
|
|
las funciones definidas en lib/datalib.php cuando sea posible - esto permite
|
|
|
|
la compatibilidad con un gran número de bases de datos. Debería
|
|
encontrar que prácticamente todo es posible utilizando estas funciones.
|
|
Si quiere escribir código SQL entonces deberá comprobar
|
|
que: funciona en cualquier plataforma; restringido a funciones específicas
|
|
de su código (normalmente un archivo lib.php); y claramente comentado.</li>
|
|
<li class="spaced">No cree o utilice variables globales distintas de las
|
|
estándar $CFG, $SESSION, $THEME y $USER.</li>
|
|
<li class="spaced">Todas las variables deberían ser inicializadas o, al menos,
|
|
comprobada su existencia utilizando isset()
|
|
o empty()
|
|
antes de ser utilizadas.</li>
|
|
<li class="spaced">Todas las cadenas deberían ser traducibles - cree
|
|
nuevos textos en los archivos "lang/es" files
|
|
con palabras reducidas en inglés y su traducción completa al
|
|
Español y recupérelas
|
|
en su código utilizando las funciones get_string() or print_string().</li>
|
|
<li class="spaced">Todos los ficheros de ayuda deben ser traducibles - cree
|
|
nuevos textos en el directorio "en/help" y llámelos utilizando
|
|
la función helpbutton().
|
|
<p>Si necesita actualizar un fichero de ayuda:</p>
|
|
<ul>
|
|
<li>para un pequeño cambio, donde la traducción antigua del
|
|
fichero podría tener todavía sentido, está permitido
|
|
que haga el cambio, pero debería notificárselo a translation@moodle.org</li>
|
|
<li>para un cambio importante tendrá que crear un nuevo fichero
|
|
añadiendole
|
|
en el nombre un numero incrementado
|
|
(p.ej. filename2.html)
|
|
para que los traductores puedan ver facilmente que se trata de una nueva
|
|
versión del archivo. Obviamente el nuevo código y los índices
|
|
de las páginas de ayuda deben ser modificados para apuntar a las
|
|
versiones más
|
|
recientes.</li>
|
|
</ul>
|
|
</li>
|
|
<li class="spaced">La información que llega desde el navegador (enviada
|
|
con los métodos GET o POST) automáticamente tiene las "magic_quotes"
|
|
aplicadas (sin importar la configuración de PHP) por lo que puedes
|
|
insertarla con total seguridad en la base de datos. El resto de la información(obtenida
|
|
desde los archivos, o desde la base de datos) debe ser escapada con la función
|
|
<font color="#339900">addslashes()</font> antes de insertarla en la base de
|
|
datos.</li>
|
|
<li class="spaced">IMPORTANTE: Todos los textos dentro de Moodle, especialmente
|
|
aquellos que han sido introducidos por los usuarios, deben ser mostrados
|
|
utilizando la función format_text(). Esto asegura que el texto es
|
|
filtrado y limpiado correctamente.</li>
|
|
</ol>
|
|
<p> </p>
|
|
<h2>Estilo del Código</h2>
|
|
<p class="normaltext">Comprendo que puede ser un poco frustrante modificar su
|
|
estilo de programación si ha trabajado en otras cosas, pero compara
|
|
esa frustración con la frustración de toda la gente que intente,
|
|
más adelante, encontrar el sentido del código de Moodle si
|
|
es una mezcla de estilos. Obviamente, hay muchos puntos a favor y en contra
|
|
de
|
|
cada estilo que la gente utiliza, pero el que se detalla aquí es el
|
|
que deberá utilizar.</p>
|
|
<ol class="normaltext">
|
|
<li class="spaced"><strong>El sangrado</strong> del texto debe ser siempre
|
|
de 4 espacios. No utilices los tabuladosres NUNCA.</li>
|
|
<li class="spaced"><strong>Los nombres de las variables</strong> tienen que
|
|
ser siempre fáciles de leer, procurando que sean palabras en minúsculas
|
|
con significado en Inglés. Si realmente necesita más de una
|
|
palabra, póngalas juntas, pero procure mantenerlas tan breves como sea posible.
|
|
Utilize nombres
|
|
en plural para las matrices de objetos.
|
|
<p class="examplecode"><font color="#006600">BIEN</font><font color="#006600">:
|
|
$quiz<br />
|
|
BIEN</font><font color="#006600"></font><font color="#006600">: $errorstring<br />
|
|
BIEN</font><font color="#006600"></font><font color="#006600">: $assignments
|
|
(for an array of objects)<br />
|
|
BIEN</font><font color="#006600"></font><font color="#006600">: $i (but
|
|
only in little loops)<br />
|
|
<br />
|
|
MAL: $Quiz <br />
|
|
MAL: $aReallyLongVariableNameWithoutAGoodReason<br />
|
|
MAL: $error_string</font></p>
|
|
</li>
|
|
<li class="spaced"><strong>Las constantes</strong> tienen que definirse siempre
|
|
en mayúsculas, y empezar siempre por el nombre del módulo al que pertenecen.
|
|
Deberían tener las palabras separadas por guiones bajos.
|
|
<p class="examplecode"><font color="#006600">define("FORUM_MODE_FLATOLDEST",
|
|
1);</font></p>
|
|
</li>
|
|
<li class="spaced"><strong>Los nombres de las funciones</strong> tienen que
|
|
ser palabras sencillas en minúsculas y en Inglés, y empezar
|
|
con el nombre del módulo al que pertenecen para evitar conflictos
|
|
entre módulos. Las palabras deberían separarse por guiones
|
|
bajos. Los parámentros, si es posible, tendrán valores por
|
|
defecto. Compruebe que no haya espacio entre el nombre de la función
|
|
y lo siguiente (paréntesis).<br />
|
|
<p class="examplecode"> <font color="#007700">function </font><font color="#0000BB">forum_set_display_mode</font><font color="#007700">(</font><font color="#0000BB">$mode</font><font color="#007700">=</font><font color="#0000BB">0</font><font color="#007700">)
|
|
{<br />
|
|
global </font><font color="#0000BB">$USER</font><font color="#007700">,
|
|
</font><font color="#0000BB">$CFG</font><font color="#007700">;<br />
|
|
<br />
|
|
if (</font><font color="#0000BB">$mode</font><font color="#007700">)
|
|
{<br />
|
|
</font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode
|
|
</font><font color="#007700">= </font><font color="#0000BB">$mode</font><font color="#007700">;<br />
|
|
} else if (empty(</font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode</font><font color="#007700">))
|
|
{<br />
|
|
</font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode
|
|
</font><font color="#007700">= </font><font color="#0000BB">$CFG</font><font color="#007700">-></font><font color="#0000BB">forum_displaymode</font><font color="#007700">;<br />
|
|
}<br />
|
|
}</font></p>
|
|
</li>
|
|
<li class="spaced"><strong>Los bloques de código</strong> siempre deben
|
|
estar encerrados por llaves (incluso si solo constan de una línea).
|
|
Moodle utiliza este estilo:
|
|
<p class="examplecode"> <font color="#006600">if (</font><font color="#0000CC">$quiz</font><font color="#006600">-></font><font color="#0000CC">attempts</font><font color="#006600">)
|
|
{<br />
|
|
if (</font><font color="#0000CC">$numattempts </font><font color="#006600">>
|
|
</font><font color="#0000CC">$quiz</font><font color="#006600">-></font><font color="#0000CC">attempts</font><font color="#006600">)
|
|
{<br />
|
|
</font><font color="#0000CC">error</font><font color="#006600">(</font><font color="#0000BB">$strtoomanyattempts</font><font color="#006600">,
|
|
</font><font color="#CC0000">"view.php?id=$cm</font><font color="#006600">-></font><font color="#CC0000">id"</font><font color="#006600">);<br />
|
|
}<br />
|
|
}</font></p>
|
|
</li>
|
|
<li class="spaced"><strong>Las cadenas </strong> tienen que ser definidas utilizando
|
|
comillas simples siempre que sea posible, para obtener un mejor rendimiento.<br />
|
|
<p class="examplecode"> <font color="#006600">$var = 'some text without any
|
|
variables';<br />
|
|
$var = "with special characters like a new line \n";<br />
|
|
$var = 'a very, very long string with a '.$single.' variable in it';<br />
|
|
$var = "some $text with $many variables $within it"; </font></p>
|
|
</li>
|
|
|
|
|
|
<li class="spaced"><strong>Los comentarios</strong> deben ser añadidos de forma que resulten prácticos, para explicar el flujo del código y el propósito de las funciones y variables.
|
|
<ul>
|
|
<li>Cada función (y cada clase) debería utilizar el popular <a target="_blank" href="http://www.phpdoc.org/">formato phpDoc</a>.
|
|
Esto permite que la documentación sea generada automáticamente.</li>
|
|
<li>Los comentarios en línea deberían utilizar los caracteres //, alineados con cuidado por encima de las líneas de código que comenta.</li>
|
|
</ul>
|
|
|
|
<p class="examplecode"><font color="#FF8000">
|
|
/**<br />
|
|
* The description should be first, with asterisks laid out exactly<br />
|
|
* like this example. If you want to refer to a another function,<br />
|
|
* do it like this: {@link clean_param()}. Then, add descriptions <br />
|
|
* for each parameter as follows.<br />
|
|
*<br />
|
|
* @param int $postid The PHP type is followed by the variable name<br />
|
|
* @param array $scale The PHP type is followed by the variable name<br />
|
|
* @param array $ratings The PHP type is followed by the variable name<br />
|
|
* @return mixed<br />
|
|
*/</font><br />
|
|
<font color="#006600">function </font><font color="#0000BB">forum_get_ratings_mean</font><font color="#007700">(</font><font color="#0000BB">$postid</font><font color="#007700">,
|
|
</font><font color="#0000BB">$scale</font><font color="#007700">, </font><font color="#0000BB">$ratings</font><font color="#007700">=</font><font color="#0000BB">NULL</font><font color="#007700">)
|
|
{<br /></font>
|
|
<font color="#007700">if (!</font><font color="#0000BB">$ratings</font><font color="#007700">)
|
|
{<br />
|
|
</font><font color="#0000BB">$ratings
|
|
</font><font color="#007700">= array(); </font><font color="#FF8000">//
|
|
Initialize the empty array</font><font color="#007700"><br />
|
|
if (</font><font color="#0000BB">$rates
|
|
</font><font color="#007700">= </font><font color="#0000BB">get_records</font><font color="#007700">(</font><font color="#DD0000">"forum_ratings"</font><font color="#007700">,
|
|
</font><font color="#DD0000">"post"</font><font color="#007700">, </font><font color="#0000BB">$postid</font><font color="#007700">))
|
|
{<br />
|
|
</font><font color="#FF8000">//
|
|
Process each rating in turn</font><font color="#007700"><br />
|
|
foreach
|
|
(</font><font color="#0000BB">$rates </font><font color="#007700">as </font><font color="#0000BB">$rate</font><font color="#007700">)
|
|
{</font> <br />
|
|
....etc </p>
|
|
</li>
|
|
|
|
|
|
<li class="spaced"><strong>El espacio en blanco</strong> se puede utilizar
|
|
con bastante libertad - no se preocupe por separar las cosas un poco para
|
|
ganar en claridad. Generalmente, debería haber un espacio entre llaves
|
|
y líneas normales y ninguno entre llaves y variables o funciones:<br />
|
|
<p class="examplecode"> <font color="#007700">foreach (</font><font color="#0000BB">$objects
|
|
</font><font color="#007700">as </font><font color="#0000BB">$key </font><font color="#007700">=></font><font color="#0000BB">
|
|
$thing</font><font color="#007700">)</font><font color="#006600"> {<br />
|
|
</font><font color="#007700"> </font><font color="#0000BB">process($thing);</font><font color="#006600">
|
|
<br />
|
|
} <br />
|
|
<br />
|
|
</font><font color="#007700">if (</font><font color="#0000BB">$x </font><font color="#007700">==
|
|
</font><font color="#0000BB">$y</font><font color="#007700">)</font><font color="#006600">
|
|
{<br />
|
|
</font><font color="#007700"> </font><font color="#0000BB">$a
|
|
</font><font color="#007700">= </font><font color="#0000BB">$b</font><font color="#007700">;</font><font color="#006600"><br />
|
|
} else if (</font><font color="#0000BB">$x </font><font color="#007700">==
|
|
</font><font color="#0000BB">$z</font><font color="#006600">) {<br />
|
|
</font><font color="#007700"> </font><font color="#0000BB">$a
|
|
</font><font color="#007700">= </font><font color="#0000BB">$c</font><font color="#007700">;</font><font color="#006600"><br />
|
|
} else {<br />
|
|
</font><font color="#007700"> </font><font color="#0000BB">$a
|
|
</font><font color="#007700">= </font><font color="#0000BB">$d</font><font color="#007700">;</font><font color="#006600"><br />
|
|
} </font></p>
|
|
</li>
|
|
</ol>
|
|
<p> </p>
|
|
<h2>Estructuras de la base de datos</h2>
|
|
<ol class="normaltext">
|
|
<li class="spaced">Cada tabla debe tener un campo autonumérico <strong>id</strong> (INT10)
|
|
como clave primaria.</li>
|
|
<li class="spaced">La tabla principal que contiene instancias de cada módulo
|
|
debe tener el mismo nombre que el módulo y contener, por lo menos, los siguientes
|
|
campos:
|
|
<ul>
|
|
<li><strong>id</strong> - descrito arriba</li>
|
|
<li><strong>course</strong> - el identificador del curso al que la instancia
|
|
pertenece</li>
|
|
<li><strong>name</strong> - el nombre completo de la instancia</li>
|
|
</ul>
|
|
</li>
|
|
<li class="spaced">El resto de las tablas asociadas con un módulo que
|
|
contiene información sobre 'cosas', deberían ser llamandas <strong>modulo_cosas
|
|
</strong>(fíjese en el plural!).</li>
|
|
<li class="spaced">Los nombres de los campos (columnas) deberían ser sencillos
|
|
y cortos, siguiendo las mismas reglas que los nombres de las variables.</li>
|
|
<li class="spaced">Cuando sea posible, las columnas que contengan una referencia
|
|
al campo id de otra tabla
|
|
(por ejemplo, <strong>modulo</strong>)
|
|
debería ser llamado <strong>moduloid</strong>.
|
|
(fíjate que esta norma es nueva y no es seguida por algunas tablas antiguas).</li>
|
|
<li class="spaced">Los campos booleanos serán implementados como enteros cortos
|
|
(por ejemplo, INT4) con los valores 0 o 1,
|
|
para permitir la futura expansión de los valores si fuera necesario.</li>
|
|
<li class="spaced">La mayoría de las tablas tienen que tener un campo <strong>timemodified</strong> (INT10)
|
|
que será actualizado con la fecha actual (timestamp de UNIX) obtenida con
|
|
la función <strong>time</strong>()
|
|
de PHP.</li>
|
|
</ol>
|
|
<p> </p>
|
|
<h2>Normas de Seguridad (y control de la información de formularios y URLs)</h2>
|
|
<ol class="normaltext">
|
|
<li class="spaced">No se base en 'register_globals'. <strong>Cada</strong> variable
|
|
debe ser correctamente inicializada en <strong>cada</strong> fichero de código.
|
|
Debe ser obvia la procedencia de cada variable.</li>
|
|
<li class="spaced">Inicialice todos los arrays y objetos aunque estén vacíos. <code>$a
|
|
= array()</code>
|
|
o <code>$obj = new stdClass();</code>.</li>
|
|
<li class="spaced">No utilice la función <code>optional_variable()</code>.
|
|
En su lugar, utilice la función <code>optional_param()</code>. Seleccione
|
|
la opción PARAM_XXXX apropiada al tipo de parámetro que espera. Para comprobar
|
|
y definir un valor opcional para una variable, utilice la función <code>set_default()</code>.</li>
|
|
<li class="spaced">No utilice la función <code>require_variable()</code>.
|
|
En su lugar, utilice la función <code>required_param()</code>. Seleccione
|
|
la opción PARAM_XXXX apropiada al tipo de parámetro que espera.</li>
|
|
<li class="spaced">Utilice <code>data_submitted()</code>, with cuidado. La información
|
|
todavía debe ser limpiada antes de utilizarla.</li>
|
|
<li class="spaced">No utilice <code>$_GET</code>, <code>$_POST</code> o<code> $_REQUEST</code>.
|
|
En su lugar, utilice las funciones <code>required_param()</code> o <code>optional_param()</code> apropiadas.</li>
|
|
<li class="spaced">No compruebe las acciones con código como: <code>if
|
|
(isset($_GET['algo']))</code>.
|
|
Utilice, por ejemplo, <code>$algo = optional_param( algo, -1, PARAM_INT
|
|
)</code> y entonces compruebe que está dentro de los valores esperados, por
|
|
ejemplo, <code>if ($something>=0) {...</code>.</li>
|
|
<li class="spaced">Cuando sea posible agrupe todas sus llamadas a <code>required_param()</code>, <code>optional_param()</code>
|
|
y el resto de inicialización de variables en el principio de cada fichero
|
|
(o función) para que sea fácilmenente localizable.</li>
|
|
<li class="spaced">Utilice el mecanismo 'sesskey' para proteger el envío de
|
|
formularios de ataques. Un ejemplo de uso: cuando el formulario es generado,
|
|
incluya <code><input
|
|
type="hidden" name="sesskey" value="<?php
|
|
echo sesskey(); ?>" /></code>.
|
|
Cuando el formulario es procesado, compruebe <code>if (!confirm_sesskey())
|
|
{error('Bad Session Key');}</code>.</li>
|
|
<li class="spaced">Todos los nombres de ficheros deben ser 'limpiados' utilizando
|
|
la función <code>clean_filename()</code>,
|
|
si esto no ha sido realizado con el uso de las funciones <code>required_param()</code> o <code>optional_param()</code>
|
|
con anterioridad. </li>
|
|
<li class="spaced">Cualquier información leída desde la base de datos debe
|
|
tener la función <code>addslashes()</code> aplicada antes de volver
|
|
a enviar la información a la base de datos. Un objeto completo puede ser
|
|
procesado con la función <code>addslashes_object()</code>.</li>
|
|
<li class="spaced">Cuando sea posible, la información que se almacenará en
|
|
la base de datos debe venir de peticiones <code>POST</code>
|
|
(por ejemplo, información de un formulario) en lugar de utilizar peticiones <code>GET</code> (por
|
|
ejemplo, información de la URL).</li>
|
|
<li class="spaced">No utilice información obtenida de <code>$_SERVER</code> si
|
|
puede evitarlo. Presenta algunos problemas de portabilidad.</li>
|
|
<li class="spaced">Si no ha sido realizado en ningún otro lugar, asegurese
|
|
de que la información enviada a la base de datos ha sido filtrada mediante
|
|
la función <code>clean_param()</code> utilizando la opción PARAM_XXXX
|
|
apropiada.</li>
|
|
<li class="spaced">Si escribe código SQL, asegurese completamente de que es
|
|
correcto. En particular, compruebe la falta de comillas en las variables
|
|
utilizadas.
|
|
Es un punto de entrada para ataques de tipo
|
|
'SQL injection'.</li>
|
|
<li class="spaced">Compruebe toda la información (especialmente la que es enviada
|
|
a la base de datos) en <strong>cada</strong>
|
|
archivo que es utilizada. Nunca confíe en que otro código estará haciendo
|
|
ese trabajo.</li>
|
|
<li class="spaced">Los bloques de código que se incluyan deben presentar una
|
|
estructura PHP correcta (por ejemplo, con una declaración de una clase,
|
|
de funciónes, etc.) -
|
|
los bloques de código lineales ("espagueti") suelen tender a utilizar variables
|
|
sin inicializar (y son menos legibles).</li>
|
|
</ol>
|
|
<hr />
|
|
<p align="center"><font size="1"><a href="." target="_top">Documentación de Moodle</a></font></p>
|
|
<p align="center"><font size="1">Version: $Id$</font></p>
|
|
</body>
|
|
</html>
|