manual de codigo
Desenvolvimento de código
Qualquer projecto colaborativo precisa de consistência e estabilidade. A criação de código para a plataforma Moodle rege-se por um guia de desenvolvimento comum a toda a comunidade. Na verdade, algum do código mais antigo não respeita exactamente estas linhas orientadoras, no entanto, este ainda pode eventualmente ser submetido a alterações. Relativamente ao novo código, todo ele deverá respeitar estes padrões.
Regras Gerais
1. Todos os ficheiros de código deverão usar a extensão .php.
2. Todos os ficheiros de templates deverão usar a extensão .html.
3. Todos os ficheiros de texto deverão usar o estilo Unix de formatação de texto.
4. Todos os tags php devem estar preenchido (por exemplo <?php ?> ao invés de <? ?>).
5. As referências de copyright já existentes deverão ser mantidas. Se necessário o criador de código pode criar as suas próprias referencias.
6. Todos os ficheiros deverão conter o include do ficheiro principal config.php.
7. Qualquer outra utilização de iclude’s/require’s deverá conter a localização completa precedida de $CFG->dirroot ou $CFG->libdir no caso de relative include’s.
8. Cada ficheiro deverá verificar se o utilizador está correctamente autenticado através das funções require_login() e has_capability() ou require_capability().
9. Todos os acessos às bases de dados deverão, sempre que possível, usar as funções definidas em lib/dmllib.php – estas permitem a compatibilidade com um vasto número de bases de dados e a grande maioria das operações desejadas. Se se pretender escrever código SQL então dever-se-á verificar se: funciona em qualquer plataforma; está restringido às funções específicas do seu código (geralmente um ficheiro lib.php); e está claramente comentado.
10. Não deverão ser criadas/utilizadas variáveis globais excepto nos standards $CFG, $SESSION, $THEME, $SITE, $COURSE e $USER.
11. Qualquer variável deverá ser inicializada ou pelo menos testada a sua existência utilizando isset() ou empty() antes de ser utilizada.
12. Todas as strings devem ser traduzíveis - Os novos textos serão criados nos ficheiros "lang/pt_utf8" com palavras concisas em inglês (letra minúscula) e sua tradução completa em português, recuperandos no código utilizando as funções get_string() ou print_string(). Não se deverão apagar strings, desta forma garante-se a compatibilidade entre os diversos packs linguísticos.
13. Não se devem usar as funções p() e s() nos prints(outputs) das strings linguísticas, estas não foram concebidas para utilizar html com tags. Para este efeito poderá ser utilizada a função echo().
14. Todos os erros deverão ser visualizados utilizando a função print_error() para maximizar a tradução e ajudar o utilizador (acedendo automaticamente ao Moodle Docs).
15. Todos os ficheiros de ajuda (help files) devem ser traduzíveis – Os novos textos devem ser criados na directoria "lang/pt_utf8/help" e acedidos através da função helpbutton(). Quando se pretender actualizar estes ficheiros:
• Para uma pequena actualização, e no caso de a tradução antiga ser minimamente credível, pode-se efectuar a alteração mas esta deve ser submetida para translation@moodle.org.
• Para alterações significativas, deve ser criado um novo ficheiro com um valor incrementado (por exemplo: filename2.html) de modo a que outros utilizadores possam compreender que se trata de uma nova versão do ficheiro em causa. Obviamente o novo código e os índices dos ficheiros de ajuda deverão ser actualizados de acordo com as versões mais recentes.
16. A informação recebida a partir do browser (utilizando os métodos GET e POST) tem automaticamente as “magic_quotes” aplicadas (independentemente das definições PHP) pelo que podem ser inseridas de forma segura na base de dados. O resto da informação (obtida a partir de ficheiros ou de bases de dados) deve ser submetida à função addslashes() antes de ser inserida na base de dados.
17. MUITO IMPORTANTE: Todos os textos dentro do Moodle, especialmente os que são introduzidos pelos utilizadores, devem ser mostrados utilizando a função format_text(). Esta assegura que o texto é filtrado e ajustado correctamente.
18. As acções dos utilizadores devem ser gravadas utilizando a função add_to_log(). Estes dados são utilizados para as “Informações de actividade” e “Registos”.
19. Para criar um link HTML, deverá utilizar a sua localização completa. Por exemplo $CFG->wwwroot/mod/blonk/view.php?id=99 em vez de view.php?id=99. Isto assegura, entre outras situações, que o código funciona se for chamado por um script noutra pasta.
Estilo do código
É compreensível que possa ser frustrante e difícil alterar o estilo de programação de cada pessoa que já tenha trabalhado noutros projectos, mas se compararmos essa frustração com a das pessoas que mais a frente irão tentar encontrar o sentido do código do Moodle, verificamos que existe a necessidade de definir algumas regras de concepção de código para que a diversidade de estilos não se mostre um entrave a percepção do mesmo. Existem, como e natural, pontos fortes e pontos fracos do estilo adoptado mas é este estilo apresentado e que se deverá utilizar.
1. Nunca utilizar tabulações ( TAB ) na identação do código. Utilizar sempre 4 espaços ( SPACE ).
2. O nome das variáveis terá de ser de fácil leitura, palavras com significado em inglês e integralmente constituídas por letras minúsculas. Se eventualmente for necessário mais de uma palavra, estas deveram estar juntas tentando serem as mais pequenas possíveis. A definição de matrizes de objectos ( arrays ) deverá ser feita através de palavras no plural.
Exemplos:
B: $quiz
B: $errorstring
B: $assignments (for an array of objects)
B: $i (but only in little loops)
M: $Quiz
M: $aReallyLongVariableNameWithoutAGoodReason
M: $error_string
Legenda: B – boa definição M – má definição
3. Todas as constantes deverão estar definidas em Maiúsculas e o seu inicio será o nome do módulo. As palavras serão separadas por “underscores”. Exemplo:
define("FORUM_MODE_FLATOLDEST", 1);
4. Os nomes de funções terão de ser compostas por palavras simples em Inglês e começaram com o nome do módulo a que pertencem para evitar conflitos com outros módulos. Estas estarão separadas por “undercores”. Se possível, todos os parâmetros terão valor por defeito. Deverá certificar-se que não existe espaço entre o nome da função e o que se lhe segue (parêntesis).
Exemplo:
function forum_set_display_mode($mode=0) {
global $USER, $CFG;
if ($mode) {
$USER->mode = $mode;
} else if (empty($USER->mode)) {
$USER->mode = $CFG->forum_displaymode;
}
}
5. Todos os blocos de código terão de ser fechados com chavetas, independentemente de serem constituídos por apenas uma linha. O Moodle utiliza este estilo:
if ($quiz->attempts) {
if ($numattempts > $quiz->attempts) {
error($strtoomanyattempts, "view.php?id=$cm->id");
}
}
6. As strings deveram estar definidas entre pelicas ( caracter ‘ ), sempre que possivel.
Exemplo:
$var = 'some text without any variables';
$var = 'with special characters like a new line '."\n";
$var = 'a very, very long string with a '.$single.' variable in it';
$var = "some $text with $many variables $within it";
7. Todo o código desenvolvido deverá ser devidamente comentado, para que o desenrolar do código seja percebido tal como o objectivo de cada função e variáveis.
• Todas as funções e classes deveram usar o formato phpDoc, para que a documentação seja automaticamente criada.
• Os comentarios de uma so linha deverão utilizar //, antes da sua descrição e deverão estar alinhados com o código que comentam e na linha anterior.
Exemplo:
/**
* The description should be first, with asterisks laid out exactly
* like this example. If you want to refer to a another function,
* do it like this: {@link clean_param()}. Then, add descriptions
* for each parameter as follows.
*
* @param int $postid The PHP type is followed by the variable name
* @param array $scale The PHP type is followed by the variable name
* @param array $ratings The PHP type is followed by the variable name
* @return mixed
*/
function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {
if (!$ratings) {
$ratings = array(); // Initialize the empty array
if ($rates = get_records("forum_ratings", "post", $postid)) {
// Process each rating in turn
foreach ($rates as $rate) {
....etc
8. O espaço em branco pode ser usado sem problema e pode ser bastante útil para separar partes de código tornando-o mais claro no geral. Geralmente, devera existir um espaço entre as chavetas de uma função e linhas normais de código, enquanto entre chavetas e variáveis ou funções não devera existir nenhum.
Exemplo:
foreach ($objects as $key => $thing) {
process($thing);
}
if ($x == $y) {
$a = $b;
} else if ($x == $z) {
$a = $c;
} else {
$a = $d;
}
9. Quando se efectuar uma copia de um determinado objecto, deverá ser sempre utilizada a função clone(), que originalmente esta disponível apenas em PHP5 (caso contrario terá apenas uma referencia para o primeiro objecto). Moodle garantira que este método funcionara, também em php4.
Exemplo:
M: $b = $a;
B: $b = clone($a);
Legenda: B – boa utilização M – má utilização
Caso o que esteja a ser copiado não seja um objecto mas sim um conjunto de objectos (ex: arrays de objectos) deverá ser utilizada a função fullclone() de forma semelhante.
Estruturas das Bases de Dados
Para a criação de tabelas devem ser tomadas em conta as seguintes regras de desenvolvimento:
1. Todas as tabelas devem ter uma variável que é automaticamente incrementada que servirá para a identificação de campos (ex. id field (INT10))
2. A tabela principal que contém instâncias de cada módulo, deve ter o mesmo nome do módulo (ex. questionário) e deve ainda conter obrigatoriamente os seguintes campos:
• Id – como foi descrito na regra anterior
• Course – id do curso a que cada instância pertence
• Name – o nome completo de cada intância do módulo
3. Outras tabelas que estejam associadas ao módulo que contenham matérias sobre “coisas” deveram ser chamadas questionário_coisas (de notar que o nome está no plural).
4. Os nomes das tabelas e das colunas devem evitar conter quaisquer palavras que esteja já reservada nas bases de dados, pelo que se recomenda uma anterior verificação das mesmas.
5. Os nomes das colunas devem ser sempre em letras minúsculas, devem ser nomes simples e pequenos, seguindo as mesmas regras aplicáveis para os nomes das variáveis.
6. Sempre que for possível, as colunas que contenham referência a um campo id de outra tabela (ex. módulo) deve ter o nome módulo_id (Nota: esta convenção não foi utilizada nas tabelas de versões iniciais do moodle).
7. Os campos booleanos devem ser implementados como campos de variáveis inteiras (ex INT4) que contêm os valores 0 ou 1, para suportarem uma posterior necessidade de essas variáveis conterem mais valores.
8. Muitas das tabelas existentes deveram ter um campo que é modificado em função do passar do tempo (INT10) que será actualizada com a data actual que pode ser obtida com a função PHP time().
9. Todos os campos devem ser inicializados com um valor inicial (que tenha sentido no contexto onde está inserido).
10. Cada nome de tabela deve começar com o prefixo da base de dados ($CFG->prefixo). Na maioria dos casos, isto é automaticamente feito. Também, no Postgres, o nome de cada índice tem de começar com o mesmo prefixo.
11. Para garantir a compatibilidade entre bases de dados devem ser seguidas simples regras como o uso da palavra chave AS (apenas de for necessário alias em tabelas\colunas, claro):
• Não usar a palavra chave AS para alias de tabelas.
• Usar a palavra chave AS para alias de colunas.
12. Nunca criar UNIQUE KEYS (restrições) sem nenhuma razão específica. Em alternativa, usar UNIQUE INDEXes. No futuro, se for decidido adicionar integridade referencial no Moodle e for necessário UNIQUE KEYS, serão usadas, mas por agora este facto não se irá verificar. De notar ainda que o editor XMLDB permite especificar restrições XMLDB-only UNIQUE e FOREIGN (o que é um ponto positivo, com o objectivo de ter o XML bem definido) mas apenas os INDEXes sublinhados serão gerados na base de dados.
13. Essas UNIQUE KEYS XMLDB-only (ler ponto anterior) apenas podem ser definidas se esse campo\campos vão ser alvo de alguma (também XMLDB-only) FOREIGN KEY. Caso contrário, devem ser criadas como UNIQUE INDEXes.
14. As tabelas associadas com um bloco devem seguir a seguinte convenção na atribuição dos seus nomes: $CFG->prefix + "block_" + nome_do_bloco+ o_restante. Por exemplo assumindo que $CFG->prefix é ‘mdl_’, todas as tabelas do bloco “rss_cliente” devem começar com ‘mdl_block_rss_client’ (sendo possível que se adicione mais palavras no final, por ex. ‘mdl_block_rss_client_outratabela’…). Esta regra será 100% forçada com o Moodle 2.0, dando entretanto tempo aos programadores. Para mais informações consultar Task 6786. 15. Nunca fazer mudanças em porções de código ESTÁVEIS. Este facto poderá provocar sérios erros quando os utilizadores actualizarem a sua versão estável para outra.
16. Quando existir referência a uma variável inteira em consultas SQL, não por o valor entre pelicas. Por exemplo, get_records_select('question', "category=$catid") está correcto. Já o exemplo get_records_select('question', "category='$catid'") está incorrecto. Este caso pode dar origem a que sejam ocultados erros em que o valor de $catid não esteja definido. (Esta thread explica este caso).
