<-- Voltar

Disposição dos Elementos

Todos os arquivos de código devem conter os seguintes elementos (se aplicáveis) na
seguinte ordem:

1. Bloco de identificação
2. Seção de includes
3. Código de declarações de classe ou interface
4. Código de instanciação de classes e processamentos diversos
5. Liberações de recursos (conexão, resultset, arrays...)
6. Cóidigo de geração de HTML

Deve existir ao menos uma linha em branco entre cada um dos elementos. Além disso,
para cada classe ou interface, deve ser observada a seguinte ordem de seus elementos:

1. Constantes
2. Atributos privados
3. Atributos protegitos
4. Atributos públicos
5. Construtores e/ou Destrutores
6. Métodos (agrupados por funcionalidades e não por escopo)

Comentário

Existem dois tipos de comentários: implementação e documentação. Comentários de implementação apenas esclarecem detalhes da lógica utilizada pelo programador, não serão posteriormente considerados na geração de documentação.

// Este é um exemplo de comentário de implementação de uma só linha 
/* Texto de comentário de implementação 
com mais de uma linha, necessário usar barra e asterisco */ 

Comentários de documentação devem seguir o formato PHPdoc, iniciando por barra e dois asteriscos:

/** Este comentário será considerado na geração da documentação */ 

PHPdoc é uma ferramenta de documentação que lê o código fonte procurando por trechos que iniciem por “/**” e terminem com “*/”. O texto encontrado entre estes caracteres é processado gerando páginas HTML. Entretanto só é considerada a documentação PHPdoc posicionada em determinados lugares do arquivo, que são:

• Imediatamente antes da declaração da classe ou interface
• Imediatamente antes da declaração do atributo
• Imediatamente antes da declaração do método

Assim um comentário PHPdoc colocado no meio de um método não será considerado.

O texto de um comentário PHPdoc também pode possuir algumas tags padrão como @param, @return e @access. Estas tags servem para posicionar o texto nas tabelas das páginas de documentação HTML geradas. Além disso, também são permitidas tags
HTML como, por exemplo, <b> e </b> para destacar algum elemento do texto.

Exemplo de comentário PHPDoc:

/** 
* Função para montar um combo de usuários. 
* @access public 
* @param int[] $idUsuario Array com os <b>Id's dos Usuários</b>. 
* @param String[] $nomeUsuario Array com os <b>Nomes dos Usuários</b>. 
* @return void 
*/ 
function comboUsuario($idUsuario, $nomeUsuario) { 
} 

Bloco de Identificação

Todo código deve iniciar com um bloco de comentários contendo a identificação da instituição, o usuário que criou o arquivo e a data de criação. Se necessário, modificações devem ser registradas neste bloco contendo o usuário, data e uma descrição resumida da alteração:

/* 
* TRIBUNAL REGIONAL FEDERAL DA 4ª REGIÃO 
* 99/99/9999 – criado por SSS 
* 99/99/9999 - Alterado por SSS: (descrição resumida...) 
*/ 

Seção de Includes

Indica quais elementos externos (declarados em outro arquivo) são referenciados pelo código, recomenda-se sempre que possível o uso de require_once:

require_once "infra/InfraMail.php"; 

Regras de Nomeclatura

Nomes de Arquivos

Devem possuir apenas letras minúsculas, números e o caracter sublinhado acrescidos da extensão “.php”.

Classes ou interfaces devem utilizar arquivos individuais, neste caso, o nome do arquivo deverá obrigatoriamente ser o mesmo da classe ou interface acrescido do sufixo “.php“

Classes e Interfaces

Nomes de classes devem ser substituidos no singular:

Pessoa, Endereco, Processo

Utilizar a primeira letra de cada palavra em maiúscula:

ProcessoAdministrativo 

Aconselha-se a supressão de preposições

SolicitacaoFerias

RequisicaoPagamento

Instâncias de Classes

Para nomear instâncias de classes utilize o prefixo obj seguido do nome da classe:

objPessoa, objEndereco, objRequisicaoPagamento 

Se for necessário utilizar mais de uma instância da mesma classe utilize um sufixo descritivo separado pelo caracter sublinhado:

ObjEndereco_Entrega, objEndereco_Cobranca

Constantes

Devem ser declaradas antes dos atrigutos e todas as letras devem estar em maiúsculo:

MEDIA

PI

Termos compostos devem ser separados por sublinhado:

TEMPO_RESPOSTA 
CONSUMO_MINIMO

Atributos

Atributos globais devem ser declarados no início do código (quando não for uma classe) e a sua referência dentro de funções logo no início da mesma.

Em classes deve-se declarar os atributos privados, após os atributos protegidos e por último os atributos públicos, separando cada grupo com uma linha em branco.

Os atributos devem ser nomeados utilizando um prefixo e um qualificador. O prefixo é definido de acordo com o tipo do atributo:

Tipo do Atributo	Prefixo	Exemplo
Número	num	NumIdade
String	str	StrNome
Data	dta	DtaNascimento
Data/Hora	dth	DthEntrega
Array	arr	ArrObjProcessos
Booleano	bol	BolEntregue

O qualificador do atributo deve descrever o melhor possível o seu significado dentro da lógica do sistema. O qualificador deve conter a primeira letra em maiúscula e as demais em minúsculas. Termos compostos devem utilizar a primeira letra de cada termo em maiúscula e as demais em minúsculas (não deve ser utilizado o caractere sublinhado):

strNome 
numArea 
numJurosAcumulados 
numIdadeMinima

Aconselha-se utilizar uma declaração por linha:

private $numNivel; 
private $strBairro; 

Atributos públicos devem ser evitados. Declare os atributos como private usando métodos de acesso (getters e setters) para prover acesso público:

 private $strNome; 
. 
. 
. 
function getStrNome() { 
return $strNome; 
} 
function setStrNome($strNome) { 
$this->strNome = $strNome; 
}

Métodos

Os nomes dos métodos devem conter apenas letras minúsculas. Termos compostos devem utilizar a primeira letra, do segundo termo em diante, em maiúscula (não deve ser utilizado o caractere sublinhado).

cadastrar 
calcularJuros 

Nomes de métodos devem ser verbos no infinitivo:

listar 
mostrarStatus 
desenharCirculo 

Métodos de acesso a um atributo de uma classe devem utilizar os prefixos get e set, seguidos do nome do respectivo atributo com a primeira letra alterada para maiúscula:

getNumTaxaEntrega, setNumTaxaEntrega 
getStrNome, setStrNome

Métodos para testar atributos booleanos de classes devem utilizar o prefixo is, seguido do nome do respectivo atributo com a primeira letra alterada para maiúscula:

isBolVencido 
isBolEnviado

Variáveis de Sessão

Variáveis de sessão devem utilizar o prefixo “S_” com todas as letras em maiúsculas. Termos compostos devem ser separados pelo caractere sublinhado:

S_USUARIO

S_NOME_SISTEMA

Variáveis Locais

Variáveis locais devem seguir as mesmas regras de nomenclatura de atributos (prefixo +qualificador):

numParcelas
numTaxaBasica

Variáveis de loop podem utilizar apenas uma letra sem prefixo. Utilize de preferência as letras i, j e k. Evite a variável l (“éle”) porque é difícil de distingüi-la do 1 (“um”) em algumas impressoras e monitores.

 

Elemento	Prefixo
[input type=] text	txt
[input type=] password	pwd
[input type=] checkbox	chk
[input type=] radio	rdo
[input type=] submit	sbm
[input type=] reset	rst
[input type=] file	fl
[input type=] hidden	hdn
[input type=] image	img
[input type=] button	btn
Form	frm
Div	div
Table	tbl
Frame	fra
iFrame	ifr
TextArea	txa
Select	sel

O qualificador deve descrever o propósito do componente e deve conter a primeira letra em maiúscula e as demais em minúsculas. Termos compostos devem utilizar a primeira letra de cada termo em maiúscula e as demais em minúsculas (não deve ser utilizado o caractere sublinhado):

btnFechar 
tblAcordaosPublicados 
txtNomeParte