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

Da AMADIS

Revisão das 03h59min 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>


Classes

Declarações de Classe

As classes devem ser nomeadas seguinto os padrões de nomenclatura.

A chave de abertura sempre deve ser escrita na linha abaixo do nome da classe (true brace form).

Toda a classe deve possuir um bloco de documentação conforme o padrão do phpDocumentator.

Apenas uma classe é permitida por arquivo.

Colocar código adicional (fora da classe) é permitido mas desencorajado. Nesses arquivos, duas linhas em branco devem separar a classe de qualquer outro código PHP no arquivo.

Este é um exemplo de uma declaração de classe aceitável:

<codehighlight language="php"> <?php /**

* Class Docblock Here
*/

class Zend_Class {

   // entire content of class
   // must be indented four spaces

} </codehighlight>

Propriedades de Classe

Todas as variáveis de classe são denominadas propriedades da classe.

Os nomes das propriedades devem seguir os padrões de nomenclatura de variáveis.

Todas as propriedades devem ser declaradas no topo da classe, antes da declaração de qualquer método.

A construção "var" não é permitida. Propriedades sempre devem declarar sua visibilidade utilizando uma das construções public, protected, private. Acessar propriedades diretamente tornando-as públicas é permitido mas desencorajado. Sugere-se manter o encapsulamento das classes utilizando métodos de "set" e "get".

Funções é Métodos

Declarações de Funções e Métodos

Funções é métodos de classes devem seguir o padrão de nomenclatura.

Métodos devem declarar sua visibilidade utilizando umas das construções private, protected ou public.

Assim como nas classes, a chave de abertura da função ou método sempre deve ser escrito na linha abaixo da declaração do nome da função. Não existe espaço entre o nome da função ou método e os parênteses para os argumentos.

Esse é um exemplo de delcarações de métodos válidos:

<codehighlight language="php"> <?php /**

* Class Docblock Here
*/

class Zend_Foo {

   /**
    * Method Docblock Here
    */
   public function sampleMethod($a)
   {
       // entire content of function
       // must be indented four spaces
   }
   
   /**
    * Method Docblock Here
    */
   protected function _anotherMethod()
   {
       // ...
   }

} </codehighlight>


A passagem de argumentos por referência em funções ou métodos é apenas permitido na sua declaração, como no exemplo abaixo:

<codehighlight language="php"> <?php function sampleMethod(&$a) {} </codehighlight>

A passagem de argumentos por referência na chamada da função é proibida.

O valor de retorno das funções não deve estar cercado por parenteses. Isso pode diminuir a legibilidade do código assim como gerar um bug caso o método seja alterado futuramente para retorno por referência.

<codehighlight language="php"> <?php function foo() {

   // WRONG
   return($this->bar);
   // RIGHT
   return $this->bar;

} </codehighlight>


Uso de métodos e funções

Os argumentos de uma função devem ser separados por apenas um espaço após a virgula. Esse é um exemplo de um uso correto para uma função com três argumentos:

<codehighlight language="php"> <?php threeArguments(1, 2, 3); </codehighlight>

A passagem de argimentos por referência é proibido no momento da chamada. Argumentos devem ser passados por referência na declaração da função.

Para as função as quais os argumentos permitem arrays, a chamada da função pode incluir a construção "array" e pode ser dividida em múltiplas linhas para aumentar a legibilidade. Nesses casos os padrões para escrever arrays ainda se aplicam:

<codehighlight language="php"> <?php threeArguments(array(1, 2, 3), 2, 3);

threeArguments(array(1, 2, 3, 'Zend', 'Studio',

                    $a, $b, $c,
                    56.44, $d, 500), 2, 3);

</codehighlight>


Comandos de Controle

If / Else / Elseif

Cláusulas de constrole baseados em "if", "else" e "elseif" devem possuir um espaço em branco antes do parênteses que abre o condicional, e um único espaço entre o que fecha e a chave de abertura.

Nas clásulas condicionais entre os parênteses, os operadores devem estar separados por espaços para legibilidade. O uso de parênteses internos é encorajado para melhorar os agrupamentos lógicos de condicionais longas.

A chave de abertura é escrita na mesma linha que a cláusula condicional. A chave de fechamento é sempre escrita em uma linha separada. Qualquer conteúdo entre as chaves deve ser identado por quatro espaços em branco.

<codehighlight language="php"> <?php if ($a != 2) {

   $a = 2;

} </codehighlight>

Para os comandos "if" que possuírem "elseif" ou "else", a formatação deve ser como nos exemplos abaixo:

<codehighlight language="php"> <?php if ($a != 2) {

   $a = 2;

} else {

  $a = 7;

}


if ($a != 2) {

   $a = 2;

} else if ($a == 3) {

  $a = 4;

} else {

  $a = 7;

} </codehighlight>

O PHP permite que esses comandos sejam escritos sem chaves em certas circunstâncias. O presente padrão exige que todos os condicionais "if", "elseif" ou "else" utilizem chaves.

O uso da construção "elseif" é permitida mas desencorajada. Sugere-se o uso da combinação "else if".

Ferramentas pessoais
Parceiros
















SourceForge.net Logo

Supported by Cenqua