DES:padroesII
Tabela de conteúdo |
Introdução
Quando um projeto é realizado em uma equipe, é necessario a definição de um padrão para a codificação, o que da ao código qualidade e clareza.
Para prover uma facilidade na hora de gerar a documentação do sistema, será usado o PHP Documentator, que é um software que le blocos de documentação em arquivos PHP, e gera um documento contendo toda a documentação do sistema.
Formatação do Arquivo PHP
Identação
Usa-se identação de 4 espaços, não podendo ser usado a tabulação.
Isto é importante pois de acordo com o programa que for usado para editar o arquivo pode tratar a tabulação de forma diferente, existem programas como o quanta que permitem a configuração de espaços por TAB.
Tamanho Máximo das linhas
O tamanho recomendado para uma linha de código é de 80 caracteres. Existem editores que setam uma linha limite que ajuda a identificar esta coluna. No entanto, linhas maiores são aceitas. O tamanho máximo para qualquer linha de código em PHP é de 120 caracteres.
Quebra de Linha
Use ENTER para a quebra de linha.
Padrões para Nomeação
Arquivos
Os arquivos devem possuir apenas caracteres alfanuméricos minúsculos em seu nome (a-z,0-9) e devem terminar com a extensão ".php".
Classes
Os nomes das classes devem ser dados conforme a localização dos arquivos dentro da estrutura de diretórios, separando seu nome por underlines ("_"). Por exemplo, a classe que esta dentro do arquivo sistema/bd.php deve se chamar Sistema_Bd.
Sendo assim, as classes devem ter como ultimo fragmento do nome o mesmo nome do arquivo que a possui, o que impossibilita portanto ter mais de uma classe no mesmo arquivo. Essa nomeação facilita uma possivel chamada a uma determinada classe. Se precisamos da classe Sistema_Bd_Consulta, ela será buscada dentro do arquivo sistema/bd/consulta.php.
Todas as partes do nome de uma classe deve ser capitalizada. Se uma sigla faz parte do nome da classe, ela tambem deve ser capitalizada. Por exemplo, o nome Sistema_PDF deve ser transformado para Sistema_Pdf.
Funções e Métodos
É permitido somente caracteres alfanuméricos, sendo que o caractere underline não é permitido.
Deve-se iniciar com uma letra minuscula. Se o nome é uma palavra composta, deve-se usar letras maiusculas no primeiro caractere da nova palavra. Essa convenção é chamada de "camelCaps".
Na orientação a objetos, os métodos de escrita e leitura a membros da classe é realizado por funções pré-fixadas com "set" e "get" respectivamente.
Variáveis
Os nomes de variáveis devem seguir o mesmo estilo "camelCaps", não sendo permitido assim o caractere underline. Numeros são permitidos, mas não são recomendados.
As variáveis devem ser composta por palavras que descrevam o seu verdadeiro propósito. Por exemplo, para uma variável de indexação, deve-se usar $indice em vez de apenas $i.
Não é permitido o reuso de variaveis, isso vai contra com o perfeito entendimento futuro do codigo.
Os nomes tanto de variáveis como de campos de tabelas devem ser grafados no singular.
Em locais onde existem mais de uma variavel sendo declarada em sequencia, é necessário que estas tenham o caractere de atribuição ("=") alinhados.
A cada declaração de variavel, é necessario que se coloque um comentario com barras duplas ("//") na frente explicando a utilização da variavel.
Exemplo:
$variavel = 'valor'; //Comentario $var = 'valor'; //Comentario $variavel2 = 'valor'; //Comentario
Constantes
As constantes devem estar em letras maiusculas, sendo permitido o uso do underline e de números.
Exemplo:
const NUMERO_PI = 3.14;
As constantes devem ser declaradas em uma classe com o operador "const". As constantes globais, definidas com a função define() são permitidas, mas em casos restritos.
Estilo de Codificação
Marcações PHP
Os códigos PHP devem ser delimitados por sua forma completa.
Exemplo:
<?php ?>
Strings
Strings Literais
Strings literais são aquelas que não contem variáveis em seu conteúdo. Ela sempre deve ser definida usando aspas simples como delimitadores.
Exemplo:
$string = 'conteúdo da string';
Strings contendo aspa simples
Quando uma string contem aspa simples em seu conteúdo, deve ser usado aspas duplas como delimitador. Esse é o unico caso onde as aspas duplas são permitidas para delimitar strings.
Exemplo:
$sql = "INSERT INTO tabela VALUES (0,'nome','sobrenome')";
String contendo variáveis
Não é permitido o uso de variáveis no meio de uma string. Para isso Deve ser usado a concatenação, que torna o código muito mais legivel. Na concatenação deve ser usado um espaço em entre a variavel e o operador de concatenação (".").
Exemplo:
$boasVindas = 'Seja bem vindo '. $nome .'!!!';
Strings muito longas
Para strings muito longas, deve ser utilizado mais de uma linha de forma concatenada. O inicio de cada linha deve estar alinhado, para um melhor entendimento do texto.
Exemplo:
$textoGrande = 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Proin nisl odio, '
.'feugiat in, ultrices a, luctus in, felis. Donec egestas erat sit amet neque. '
.'Aliquam urna metus, condimentum vitae, pharetra nec, dictum eu, purus.'
Arrays
Indexadas por números
Não devem ser usados numeros negativos como indices de arrays.
É recomendado que as arrays se iniciem em 0. Outros numeros positivos são permitidos, porem não recomendados.
Quando declarada uma string com o construtor "String", deve ser usado um espaço em branco para separar a virgula dos valores do Array
Exemplo:
$alunos = array('João' , 'Pedro' , 'Manuel');
Declarar um array em varias linhas é permitido, porem deve seguir a identação indicada a seguir:
$alunos = array('João' , 'Maria' , 'Samuel'
'Manuel' , 'Antonio', 'Sebastião'
'Marcos' , 'Rafaela' , 'Manuela');
Arrays Associativos
Quando se declara um array associativo, é necessário separar cada elemento em linhas diferentes.
Exemplo:
$array = array('primeiro' => 'Marcos',
'segundo' => 'Maria',
'terceiro' => 'Antonio');
Classes
Declaração
O nome da classe deve seguir a nomeação definida anteriormente.
Todas as classes devem conter um bloco de documentação, conforme as especificações do PHPDocumentator.
O caractere de inicio de bloco ("{") deve estar na linha seguinte a declaração da classe.
Somente uma classe é permitida em cada arquivo php.
Exemplo de uma declaração de classe:
/**
* Documentação da Classe
*/
classe Classe_Exemplo
{
//Conteúdo da classe
//precisa ser identado com quatro espaços
}
Variáveis pertencentes a Classe
Devem ser nomeadas conforme definido anteriormente.
Qualquer variável deve estar declarada no inicio do escopo da Classe.
O construtor var não é permitido. As variaveis sempre devem conter sua visibilidade, usando os construtores public, private e protected.
As variaveis com permissões public e protected devem iniciar necessariamente com um underline ("_").
É permitido o acesso direto a variavel, porem não é aconselhavel. Recomenda-se o uso das funções de acesso get e set.
Funções e Métodos
Declaração
A nomeação deve seguir as convenções anteriormente definidas.
Métodos devem ter sempre sua visibilidade definida usando os construtores public, private e protected.
Assim como nas classes, o caractere de inicio de bloco ("{") deve estar na linha seguinte a declaração do método ou da função, sendo que nesta linha deve conter apenas este caractere.
Os métodos devem ser antecedidos por um bloco de documentação seguindo as especificações do PHP Documentator.
Exemplo:
/**
* Documentação da Classe
*/
classe Classe_Exemplo
{
public $variavelPublica;
private $_variavelPrivada;
protected $_variavelProtegida;
/**
* Documentação do Método
*/
public metodoProtegido()
{
//Conteudo do método
}
}
O retorno da função não deve estar entre parenteses. Isso não ajuda na legibilidade do código.
function teste()
{
//Errado
return($variavel);
//Certo
return $variavel;
}
Retornos booleanos devem ser grafados em letras maiúsculas. TRUE e FALSE
Estrutas de Controle
if / then / else if
Os construtores if, else e else if devem estar separados do parentese delimitador das condições por um espaço.
O caractere de inicio de bloco ("{") deve estar na mesma linha do comando if/if else/else, separado do parenteses delimitador das condições por um espaço.
Todos os operadores devem estar entre espaços.
O conteúdo entre os marcadores de bloco devem seguir o padrão de identação (quatro espaços).
Exemplo:
if ($a == 2) {
//Conteudo
} else if ($a == 3) {
//Conteudo
} else {
//Conteudo
}
Não deve ser usados estruturas de condição sem os delimitadores de bloco ("{" e "}")
Switch
O construtor switch deve ser separado por um espaço em branco do abre parenteses da condição, e deve existir um espaço em branco entre o fecha parenteses e o inicio de bloco ("{")
O inicio de bloco ("{") deve ficar na mesma linha da declaração do switch.
As condições devem ser identadas com quatro espaços em branco. O conteudo destas devem ser identados com mais quatro espaços em branco.
O construtor default deve sempre estar presente em uma estrutura switch.
Exemplo:
switch ($variavel) {
case 1:
//Conteudo
break;
case 2:
//Conteudo
break;
default:
//Conteudo
break;
}
Documentação
Todos os blocos de documentação devem seguir os padrões do PHP Documentator.
Todas os arquivos, classes, métodos e funções devem conter um bloco de documentação descrevendo os mesmos.
Arquivos
Todos os arquivos devem conter uma declaração do mesmo, nos padrões do PHP Documentator, com no minimo as seguintes informações:
/** * nomeDoArquivo.php * * Pequena descrição do arquivo * * Grande descrição do arquivo * * @copyright 2006 4Line * @author Nome Sobrenome * @version Versão do Arquivo * @since Arquivo disponivel desde a versão x.x.x */
Classes
Todas as classes devem conter no bloco de documentação no minimo as seguintes informações:
/** * Nome_da_Classe * * Pequena descrição da Classe * * Grande descrição da Classe * * @copyright 2006 4Line * @version Versão da Classe * @author Nome Sobrenome * @since Classe disponível desde a versão x.x.x */
Métodos/Funções
Todas as métodos e funções devem conter um bloco de documentação com no minimo:
- Nome
- Descrição
- Todos os parametros com descrição
- Todos os possiveis valores de retorno
- Se uma função gera uma exceção, deve conter na documentação o valor @throws
