Talvez a maior dificuldade após aprender uma linguagem de programação é como estruturar
os sistemas. Aprenda aqui uma metodologia de estruturação de sites e sistemas web
(arquivos, código fonte, nomenclatura, etc.).
Antes de tudo, esse artigo não é baseado em nenhum autor, nem uma metodologia With A Complex English Name. Por minha
experiência em ficar fuçando tudo quanto é sistema open-source, e em passar madrugadas
a fio resolvendo problemas nos meus sistemas, principalmente aqueles em que eu via
a mesma declaração em 500 partes diferentes, eu acabei desenvolvendo um método próprio
de organização e estruturação dos arquivos e do código fonte. Talvez seja um tema
já óbvio e que vocês estejam cansados de ouvir. Mas sempre tem algo novo a aprender.
Ah, vale lembrar que o que mostro é válido tanto para sistemas quanto para sites
(eu usarei a palavra sistema no decorrer do artigo, mas pense como:
sistema = site, site = sistema).
Não basta aprender uma linguagem de programação e se tornar o mais especialista
do mundo nela caso não se tenha noção de organização e estruturação do sistema.
Que adianta saber escrever uma super-classe-fantástica,
mas no final das contas você está perdido porque seu código está uma zona, você
não sabe aonde incluir isso, aonde declarar aquilo e assim por diante.
Se eu for explicar tudo em um só artigo, vai ficar longo e cansativo, então está
dividido da seguinte maneira:
Parte 1
-
Ordem e localização dos arquivos;
-
Nomenclatura dos arquivos;
-
Nomenclatura no código;
-
Estilo de codificação;
Parte 2
-
Separação da lógica do visual;
-
Ordem e local de inclusão de arquivos;
-
Ordem e local de criação de objetos;
-
Onde conectar com o banco de dados;
-
Separação de seções (módulos);
Parte 3
-
Como estruturar uma área administrativa (painel de controle);
-
Formulários: em que ordem e qual a lógica de obter dados, validar, retornar erro
e depois salvar?
-
Estabilidade;
1) Ordem e localização dos arquivos
Um dos itens mais importantes é onde colocar todos os arquivos. Pois afinal de contas,
o sistema é basicamente um aglomerado de arquivos!
Estrutura das pastas:
nome_do_projeto/
|--- doc/
|--- layout/
|--- sql/
|--- www/
|--- cache/
|--- galeria/
|--- lib/
|--- modulos/
|--- templates/
+ A pasta raiz é de o nome identificador
do seu projeto. Eu sempre uso nome da empresa cliente, exemplo:
petrobras/.
+ doc é a pasta que contém todos os
documentos relacionados ao projeto: contrato, anotações de idéias, propostas, leiame
com as configurações para que o sistema funcione corretamente, etc.
+ layout é a pasta que contém o layout
“cru”, pronto para ser desmontado em html e jogado na programação. Contém também
os arquivos de edição originais, exemplo arquivos de photoshop.
+ sql contém os .sql com a estrutura
do banco de dados e também dumps de backup.
+ www onde fica o principal: códigos,
layout montado, bibliotecas, galeria, etc:
+ www/galeria – fotos dos itens do sistema.
Exemplo: numa loja virtual, há as fotos dos produtos, então dentro da galeria tem
mais uma pasta chamada produtos que por sua vez contém as fotos dos produtos.
+ www/lib – todas as classes de framework
e funcionalidades em geral ficam aqui armazenadas.
+ www/modulos – classes das seções do
sistema (módulos).
+ www/templates – toda a parte estética
fica armazenada aqui. Normalmente contém as pastas:
css, imagens, flash e js. São auto-explicativas.
2) Nomenclatura dos arquivos
+ Toda classe deve estar
presente num arquivo que contenha apenas ela, sem qualquer outro tipo de código.
O nome do arquivo deve ser: class.nomedaclasse.php
e deve estar contida na pasta www/lib.
+ Todo
arquivo de inclusão deve possuir o nome: finalidade.inc.php.
+ Arquivos de HTML:
nome.tpl e contidos em www/templates.
+ Como um
módulo é uma classe, seu arquivo também deve se chamar
class.nomedomodulo.php e estar em www/modulos.
3) Nomenclatura no código
+ Variáveis, Argumentos, Funções e Classes:
usar a notação Pascal, onde todas as palavras iniciam com letra maiúscula, exemplos:
$ProdutoNome = 'Livro';
Class CarrinhoCompras
function ObtemPedido($PedidoId)
+ Ao nomear uma função / método, procure
sempre colocar a ação por primeiro e depois o porquê da ação, exemplo:
class Usuarios
{
function ObtemEmail($UsuarioId)
...
+ Constantes todas em maiúsculas:
define('TB_USUARIOS',
'blah');
4) Estilo de Codificação
Talvez a seção 3 acima se encaixasse aqui, mas preferi separar, fica mais claro.
+ ESPAÇOS: Sempre coloque espaço entre
cada token (cada item de código, exemplo:
+, (, $variável, etc) e sempre coloque parenteses onde for possível.
NÃO:
$Soma=3+4*3+2;
SIM:
$Soma = 3 + (4
* 3) +
2;
+
BLOCOS DE CÓDIGO: Sempre abra e feche colchetes nos blocos de código, mesmo
que sejam de apenas um comando. E cada colchete deve ficar individualmente em uma
linha.
NÃO:
if(true) echo 'OK';
else echo 'Não';
for($i=10;$i
< 100;$i++)
{
printf('%d<br/>', $i);
FazerAlgo();
}
SIM:
if(true)
{
echo 'OK';
}
else
{
echo 'Não';
}
for($i = 10;
$i < 100;
$i++)
{
printf('%d<br/>',
$i);
FazerAlgo();
}
+
STRINGS: Usar aspas simples para strings. Não colocar variáveis
dentro de string, deve-se abrir e fechar concatenação:
NÃO:
$Endereco = "Rua: $ClienteRua, $ClienteNumero";
$Nomes["clienteTal"] =
"Willian";
SIM:
$Endereco = 'Rua: ' .
$ClienteRua . ', ' .
$ClienteNumero;
$Nomes['clienteTal'] =
'Willian';
Ou, usar sprintf / printf, que é muito mais profissional e
claro de se ler (veja mais em http://br2.php.net/manual/pt_BR/function.sprintf.php
):
$Endereco =
sprintf('Rua: %s, %s',
$ClienteRua,
$ClienteNumero);
+
COMENTÁRIOS: Comentar toda classe, função, atributo, constante e variável
principal usando o estilo JavaDoc / PhpDocumentor. E sempre cada novo bloco de código
principal.
O que é PhpDocumentor? Bom, eu não vou explicar aqui como funciona, porque senão
teria que dividir esse artigo em 1000 partes. Segue manual completo:
http://www.phpdoc.org/.
Irei explicar aqui o básico do PhpDoc, praticamente o necessário para comentar seu
código adequadamente:
Seus blocos de códigos devem ser dessa maneira:
/**
* Descrição principal do que está comentando.
*
* @param integer $Id Identificador
da Ação na BOVESPA
*
@param string $Usuario Código do usuário
* @since 22/02/06
* @author Alfred R. Baudisch<email@email.com>
* @return array
*/
function ObtemAcoes($Id, $Usuario)
- Coloque sempre um bloco desse tipo em cima de suas funções. Para todos os parametros
da função, coloque um @param.
- @return é o que a função retorna (exemplo:
array). No caso de não retornar nada, coloque
@return void.
- Para classes, retire o @param e
@return e escreva a descrição da mesma:
/**
* Manipuladora de carrinho de compras.
*
* Características:
* - Adiciona produto;
* - Calcula frete;
* etc...
*
* @since 22/02/06
* @author Alfred R. Baudisch<email@email.com>
*/
class Carrinho ...
- Para atributos de classe, use:
/**
* Nome do cliente
* @var tipo $Nome
*/
var $Nome;
- Para constantes, use o mesmo tipo de bloco, mas ela não possui nenhuma tag @.
- Para comentar blocos de código importantes, tal como um while que obtém os usuários,
use a seguinte formatação:
// ----------------------------
// Obtém usuários
// ----------------------------
while($Dados = $DB->FetchNum())
{
// Obtém Id
$Id =
$this->ObtemId($Dados['cod']);
...
Ou seja, em blocos que executam uma série de ações, mas que se resumem a uma finalidade
abrangente (exemplo: apagar produtos), coloque duas linhas de traços e a descrição
no meio dos traços no começo do bloco.
Para blocos de ações mais comuns, (ações dentro desse bloco importante, na ação
apagar produtos, para um produto envolve a ação obter o produto, apagar a foto e
apagar o registro do banco de dados), use o comentário C++ ( // ) em uma linha mesmo.
Ainda existem dezenas de outras tags @. Tal como @link, @see, @version, @access,
etc mas isso você aprende no http://www.phpdoc.org/ porque a minha intenção aqui
é lhe mostrar padrões a seguir e não a dominar o PhpDOC!
E aqui encerra essa primeira parte! Para saber o que vem na próxima, verifique o
indíce no topo desse artigo. Eu vou tentar concluir ela para daqui 1 semana, fiquem
antenados!
Até mais!
Alfred Reinold Baudisch
alfred@auriumsoft.com.br
www.auriumsoft.com.br/blog/
Auriumsoft – Inteligência,
Tecnologia e Vídeo
www.auriumsoft.com.br
AuriumHost – Hospedagem
de qualquer tecnologia e banco de dados!
www.auriumhost.com.br