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.).    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 arquivosUm 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çãoTalvez 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!