2004-07-08 21:10:56 +00:00
< html >
< head >
2004-08-31 10:39:17 +00:00
< title > Moodle Docs: manual de estilo del có digo< / title >
2004-07-08 21:10:56 +00:00
< link rel = "stylesheet" href = "docstyles.css" type = "TEXT/CSS" >
< meta http-equiv = "Content-Type" content = "text/html; charset=iso-8859-1" >
< / head >
< body bgcolor = "#FFFFFF" >
< h1 > Manual de Estilo del Có digo< / h1 >
2004-07-09 08:09:43 +00:00
< p class = "normaltext" > Cualquier proyecto colaborativo necesita que la consistencia
2004-07-08 21:10:56 +00:00
y la estabilidad sean fuertes.< / p >
2004-07-09 08:09:43 +00:00
< 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 en breve. Todo el có digo
nuevo definitivamente deberá adherirse a estos está ndares de la
forma má s exacta posible.< / p >
2004-07-08 21:10:56 +00:00
< 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. Puedes
incluir los tuyos propios si resulta necesario.< / li >
2004-07-09 08:09:43 +00:00
< li class = "spaced" > Todos los archivos deben incluir el archivo principal config.php.< / li >
2004-07-08 21:10:56 +00:00
< 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 >
2004-07-09 08:09:43 +00:00
< 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í as
encontrar que prá cticamente todo es posible utilizando estas funciones.
Si quieres escribir có digo SQL entonces deberá s comprobar que:
funciona en cualquier plataforma; restringido a funciones especí ficas
de tu có digo (normalmente un archivo lib.php); y claramente comentado.< / li >
2004-07-08 21:10:56 +00:00
< li class = "spaced" > No crees o utilices 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 - crea nuevos
textos en los archivos " lang/es" files
con palabras reducidas en inglé s y su traducció n completa al Españ ol y recupé ralas
en tu có digo utilizando las funciones get_string() or print_string().< / li >
2004-08-24 22:13:16 +00:00
< li class = "spaced" > Todos los ficheros de ayuda deben ser traducibles - crea
nuevos textos en el directorio " en/help" y llá malos utilizando
la funció n helpbutton().
< p > Si necesitas actualizar un fichero de ayuda:
< ul >
< li > para un pequeñ o cambio, donde la traducció n antigua del fichero
podrí a tener todaví a sentido, está permitido que hagas el cambio, pero
deberí as notificá rselo a translation@moodle.org< / li >
< li > para un cambio importante tendrá s 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 >
< / p >
< / li >
2004-07-09 08:09:43 +00:00
< 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 >
2004-08-24 21:51:31 +00:00
< li class = "spaced" > IMPORTANTE: Todos los textos dentro de Moodle, especialmente
aqueloos 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 >
2004-07-08 21:10:56 +00:00
< / ol >
< p > < / p >
< h2 > Estilo del Có digo< / h2 >
2004-07-09 08:09:43 +00:00
< p class = "normaltext" > Comprendo que puede ser un poco frustrante modificar tu
estilo de programació n si has 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á s utilizar.< / p >
2004-07-08 21:10:56 +00:00
< 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 necesitas má s de una palabra, ponlas
juntas, pero procura mantenerlas tan breves como sea posible. Utiliza 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 >
2004-07-09 08:09:43 +00:00
< 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.
Fí jate en que no haya espacio entre el nombre de la funció n
2004-07-08 21:10:56 +00:00
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 >
2004-07-09 08:09:43 +00:00
< 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:
2004-07-08 21:10:56 +00:00
< 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 > utilizará n dos o tres barras
y estará n alineados con el có digo
< p class = "examplecode" > < 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 = "#FF8000" > /// Return the mean rating of a post given
to the current user by others.< br / >
/// Scale is an array of possible ratings in the scale< br / >
/// Ratings is an optional simple array of actual ratings (just integers)< br / >
< 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 te preocupes 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 >
2004-07-09 08:09:43 +00:00
< 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í jate en el plural!).< / li >
2004-07-08 21:10:56 +00:00
< 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 >
< 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 >
