Como organizar os arquivos e o código fonte de um site ou sistema web (parte 1 de 3)

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.)

por Alfred Reinold Baudisch

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

1. Ordem e localização dos arquivos;
2. Nomenclatura dos arquivos;
3. Nomenclatura no código;
4. Estilo de codificação;

Parte 2

5. Separação da lógica do visual;
6. Ordem e local de inclusão de arquivos;
7. Ordem e local de criação de objetos;
8. Onde conectar com o banco de dados;
9. Separação de seções (módulos);

Parte 3

10. Como estruturar uma área administrativa (painel de controle);
11. Formulários: em que ordem e qual a lógica de obter dados, validar, retornar erro e depois salvar?
12. 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");
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;

// Obtém usuários
// ----------------------------
while($Dados = $DB->FetchNum())
{
// Obtém Id
$Id = $this->ObtemId($Dados["cod"]);
...
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