Padrões de Codificação do AMADIS 1.x

Da AMADIS

Revisão das 03h14min de 21 de Junho de 2006 por Juliano (discussão | contribs)

Índice

Introdução

Escopo do Documento

Este documento contém os padrões de codificação e guidelines para os desenvolvedores trabalhando no AMADIS. Os tópicos cobertos aqui são:

  • Formato dos arquivos PHP
  • Padrões de nomeação
  • Estilos de programação
  • Documentação dos arquivos

Objetivos

Bons padrões de codificação são importantes em qualquer projeto de desenvolvimento, especialmente quando muitos programadores estão envolvidos. A existência desses padrões ajuda a garantir que o código seja de alta qualidade, possua menos bugs e seja facilmente mantido.

Formato dos Arquivos PHP

Geral

Para os arquivos que contenham apenas código PHP, o tag de fechamento ("?>") deve ser omitido. Isso não é uma exigência do PHP, mas a omissão evita que espaços em branco após o tag sejam acidentalmente injetados na saída do script.

Indentação

Use uma identação de 4 espaços e nenhum caracter de tabulação. Os editores devem serem configurados para tratar tabs como espaços para evitar a injeção de tabulações no código fonte.

Tamanho máximo das linhas

Os desenvolvedores devem tentar manter o tamanho das linhas em 80 caracteres. Entretanto, linhas maiores são aceitas. O tamanho máximo de uma linha deve ser de 120 caracteres.

Final de Linha

O final de linha (line terminarion) é o padrão para arquivos de texto do UNIX. Linhas devem terminar apenas com um sinal de linefeed (LF). Linefeeds são representados pelo caracter decimal 10, ou o hexadecimal 0x0A.

Não utilize carriage returns (CR) como nos computadores Macintosh.

Não utilize a combinação carriage returns/linefeed (CRLF) como nos computadores com Windows (0x0D, 0x0A).

O final das linhas não devem conter espaços. Como forma de facilitar essa convenção, a maior parte dos editores podem ser configurados para retirar os caracteres no final das linhas (strip trailing spaces).

Padrões de nomeação

Classes

por definir


Nomes de Arquivo

Para todos os arquivos apenas caracteres alfanuméricos, underscores ("_") and hífes ("-") são permitidos. Espaços são proibidos.

Qualquer arquivo que contenha código PHP deve terminar com a extensão ".php".

Os nomes de arquivos devem corresponder aos padrões de nomeação das classes. Deve-se prestar atenção na caixa da letra. Ela deve coincindir com o nome da classe.

Funções e Métodos

Nomes de função devem conter apenas caracteres alfanuméricos. Underscores não são permitidos. Números são permitidos, mas são desencorajados.

Nomes de função devem sempre começar com uma letra minuscula. Quando um nome de função for formado por mais de uma palavra, a primeira letra de cada uma delas deve ser maiuscula. Esse médoto é usualmente denominado de "studlyCaps" ou "camelCaps".

Expressividade é encorajada. Nomes de função devem ser tão ilustrativas quando possível para aumentar a compreensividade.

Nomes de função devem ser escritos em inglês para aumentar a possibilidade de internacionalização do sistema.

Estes são exemplo de nomes de função aceitáveis:

  • filterInput()
  • getElementById()
  • listForums()
  • listUsers()

Como o AMADIS é programado utilizando orientação à objetos, métodos de acesso para membros de um objeto devem ser sempre prefixados com as palavras "get" e "set". Quando utilizando design patterns, tais como Singletons e Factories, o nome do método deve conter um padrão de nomenclatura que torne o padrão mais facilmente reconhecido.


Apesar dos nomes de função não poderem conter o caractér de underscore, métodos de classes que são declarados protegidos ou privados devém começar com um único underscore, como no exemplo:

<codehighlight language="php"> <?php class Zend_Foo {

   protected function _fooBar()
   {
       // ...
   }

} </codehighlight>

Funções no escopo global, ou "funções flutuantes", são permitidas, mas desencorajadas. É recomendável que essas funcções sejam mapeadas para uma classe de declaradas estáticas.

Variáveis

Os nomes de variáveis devem ser escritos em inglês. Eles podem conter apenas caracteres alfanuméricos. Underscores não são permitidos. Números são permitidos mas desencorajados.

Quando as variáveis forem propriedades de classes e declaradas como privadas ou protegidas, o primeiro caractér do nome deve ser um único underscore. Esse é o único uso aceitável do underscores no nome de uma variável. Propriedades declaradas públicas nunca devem começar com um underscores. Por exemplo:


For class member variables that are declared with the private or protected construct, the first character of the variable name must be a single underscore. This is the only acceptable usage of an underscore in a variable name. Member variables declared as "public" may never start with an underscore. For example:

<codehighlight language="php"> <?php class Zend_Foo {

   protected $_bar;

} </codehighlight>

Como nos nomes de função, variáveis devem começar com letras minúsculas e seguir o padrão de caixa "camelCaps".

Expressividade é encorajada. Nomes de variáveis devem serem tão expressivão quanto for prático. Nomes pequenos, como "$i" e "$n" são desencorajados para qualquer outro uso que não em pequenos loops. Se um loop contiver mais do que 20 linhas de código, os nomes dos índices ou contadores devem ser descritivos.


Constantes

Contantes podem conter tanto caracteres alfanuméricos quanto underscores. Números são permitidos em nomes de constantes.

Os nomes de constantes devem sempre serem em caixa alta.

Para aumentar a legibilidade, as palavras em nomes de constante devem serem separadas por caractéres de underscore. Por exemplo, "EMBED_SUPPRESS_EMBED_EXCEPTION" é permitido mas "EMBED_SUPPRESSEMBEDEXCEPTION" não.

Constantes devem ser definidas como membros de classes utilizando a construção "const". Definir constantes de escopo global utilizando "define" é permitidos mas desencorajado.


Estilo de codificação

Demarcação do código PHP

O código PHP devem sempre ser delimitado pelos tags PHP padrão em sua forma completa (levando em consideração a nota sobre os tags de fechamento)

<codehighlight language="php"> <?php

?> </codehighlight>

Tags curtos (short tags) não são permitidos.

Strings

Strings literais

Quando uma string é literal, ou seja, não contém substituições de variáveis, o apóstrofo (single quote) deve sempre demarcá-la:

$a = 'String de exemplo';

Strings literais contendo apóstrofos

Quando a própria string contiver apóstrofos, é permitido demarcá-la com aspas (double quotes).

$sql = "SELECT `id`, `name` from `people` WHERE `name`='Juliano' OR `name`='Silvia';

A sintaxe acima deve ser utilizada ao invés de "escapar" (escaping) os apóstrofos.

Substituição de variáveis

A substituição de variáveis é permitida utilizando uma das duas formas:

<codehighlight language="php"> <?php $greeting = "Hello $name, welcome back!";

$greeting = "Hello {$name}, welcome back!"; </codehighlight>

Por questões de consistência, a seguinte forma não é permitida.

<codehighlight language="php"> <?php $greeting = "Hello ${name}, welcome back!"; </codehighlight>

Concatenção de Strings

Strings podem ser concatenadas utilizando-se o operador ".". Um espaço deve sempre ser adicionado antes e depois do operador "." para aumentar a legibilidade:

$test = "My" . "test";

Quando duas strings são concatenadas com o operados ".", é permitido quebrar o comando em múltiplias linhas para aumentar a legibilidade. Nesses casas, cada nova linha deve ser preenchida com espaços de tal forma que o operador "." fique alinhado com o operador "=":

<codehighlight language="php"> <?php $sql = "SELECT `id`, `name` FROM `people` "

    . "WHERE `name` = 'Susan' "
    . "ORDER BY `name` ASC ";

</codehighlight>


Arrays

Arrays indexados numéricamente

Número negativos não são permitidos como índices de arrays.

O índice de um array pode começar por um número não-negativo, entretanto encoraja-se e recomenda-se que todos tenham 0 como base.

Quando se declarar um array com a construção "array", um espaço deve ser adicionado entre cada vírgula para aumentar a legibilidade.


<codehighlight language="php"> <?php $sampleArray = array(1, 2, 3, 'Plataform', 'AMADIS'); </codehighlight>

Também é permitido declarar arrays indexados em múltiplas linhas. Nesse caso, cada linha sucessiva deve ser alinhada com da seguinte forma:

<codehighlight language="php"> <?php $sampleArray = array(1, 2, 3, 'Plataform', 'AMADIS',

                    $a, $b, $c
                    55.44, $d, 500);

</codehighlight>

Arrays Associativos

Ao se declarar arrays associativos com a construção "array", encoraja-se a quebrar o comando em múltiplas linhas. Nesse caso, cada linha sucessiva deve ter espaços em branco adicionados no inicio de forma que tanto as chaves quanto os valores fiquem alinhados:

<codehighlight language="php"> <?php $sampleArray = array('firstKey' => 'firstValue',

                    'secondKey' => 'secondValue');

</codehighlight>

Ferramentas pessoais
Parceiros
















SourceForge.net Logo

Supported by Cenqua