+9
Organização de Arquivos e Código Fonte para um Sistema Web (Parte 1)
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.
<font color="red">NÃO:</font>
$Soma=3+4*3+2;
<font color="blue">SIM:</font>
$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.
<font color="red">NÃO:</font>
<font color="blue">SIM:</font>
+ STRINGS: Usar aspas simples para strings. Não colocar variáveis dentro de string, deve-se abrir e fechar concatenação:
<font color="red">NÃO:</font>
<font color="blue">SIM:</font>
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 ):
+ 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:
- 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:
- Para atributos de classe, use:
- 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:
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 na primeira página desse artigo.
Uma versão bem formatada desse artigo se encontra (Word DOC):
http://www.auriumsoft.com.br/alfred/artigos/organizar_1.zip
Até mais!
Alfred Reinold Baudisch
http://www.auriumsoft.com.br/blog/
Auriumsoft
http://www.auriumsoft.com.br/
AuriumHost
http://www.auriumhost.com.br/
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.
<font color="red">NÃO:</font>
$Soma=3+4*3+2;
<font color="blue">SIM:</font>
$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.
<font color="red">NÃO:</font>
<?php
if(true) echo 'OK';
else echo 'Não';
for($i=10;$i < 100;$i++) {
printf('%d<br/>', $i);
FazerAlgo();
}
<font color="blue">SIM:</font>
<?php
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:
<font color="red">NÃO:</font>
<?php $Endereco = "Rua: $ClienteRua, $ClienteNumero"; $Nomes["clienteTal"] = "Willian";
<font color="blue">SIM:</font>
<?php $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 ):
<?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:
<?php /** * 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:
<?php /** * 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:
<?php /** * 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:
<?php
// ----------------------------
// 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 na primeira página desse artigo.
Uma versão bem formatada desse artigo se encontra (Word DOC):
http://www.auriumsoft.com.br/alfred/artigos/organizar_1.zip
Até mais!
Alfred Reinold Baudisch
http://www.auriumsoft.com.br/blog/
Auriumsoft
http://www.auriumsoft.com.br/
AuriumHost
http://www.auriumhost.com.br/
O que mais me interessou sim foi a nomenclatura dos arquivos... meus sistemas estão crescendo e já estou começando a me confundir!
Parabéns pelo Artigo!
abraços
Parabéns pelo Artigo!
abraços
13/09/2006 4:19am
(~18 anos atrás)
Parabéns pelo ótimo artigo.
Além do padrão Pear também há o padrão de codificação proposto para o Zend Framework.
O link para a documentação em português é http://framework.zend.com/manual/pt-br/coding-standard.html
Abraços.
Além do padrão Pear também há o padrão de codificação proposto para o Zend Framework.
O link para a documentação em português é http://framework.zend.com/manual/pt-br/coding-standard.html
Abraços.
25/08/2006 3:33pm
(~18 anos atrás)
Muito bom artigo, álias, como vc controla versão dos arquivos que vc vai validando??
Abs
Abs
17/07/2006 5:08am
(~18 anos atrás)
Alfred... bom trabalho... principalmente com relação a organização dos arquivos fisicamente. Geralmente, cada pessoa tem sua maneira de organizar, mas um padrão ajuda muito pra universalizar.
Atualmente eu uso o PHPDoc que vc recomendou. Porém, com relação a nomemclatura de clases, métodos... prefiro manter o padrão Java.
Na verdade, com a solução PHPDoc + nomenclatura java no final, toda documentação e organização fica padrão Java! Assim é muito bom pq você adota um padrão de reconhecimento mundial!!
To com a idéia de publicar 2 artigos para complementar seu artigo Alfred (sua ajuda seria preciosa... rsrsrsr). Um citando as metodologias para engenharia do sistema/sw como notação UML, RUP, MR e MER e um sobre controle de versões no PHP (esse eu quero muito estudar... dai divulgo meus resultados).
Caso exista algo pronto aqui sobre isto.... seria bom conferir.
Atualmente eu uso o PHPDoc que vc recomendou. Porém, com relação a nomemclatura de clases, métodos... prefiro manter o padrão Java.
Na verdade, com a solução PHPDoc + nomenclatura java no final, toda documentação e organização fica padrão Java! Assim é muito bom pq você adota um padrão de reconhecimento mundial!!
To com a idéia de publicar 2 artigos para complementar seu artigo Alfred (sua ajuda seria preciosa... rsrsrsr). Um citando as metodologias para engenharia do sistema/sw como notação UML, RUP, MR e MER e um sobre controle de versões no PHP (esse eu quero muito estudar... dai divulgo meus resultados).
Caso exista algo pronto aqui sobre isto.... seria bom conferir.
24/06/2006 6:10am
(~18 anos atrás)
Olá amigo !
Seu artigo é bem simples, porém, muito util !
A dica do PhpDocumentor foi também muito boa ! Trata-se realmente de uma ferramenta facilitadora para nós programadores !
Parabéns !
<a href="http://www.virtuacenter.com.br/tiago">Tiago Gouvêa</a>
Seu artigo é bem simples, porém, muito util !
A dica do PhpDocumentor foi também muito boa ! Trata-se realmente de uma ferramenta facilitadora para nós programadores !
Parabéns !
<a href="http://www.virtuacenter.com.br/tiago">Tiago Gouvêa</a>
01/06/2006 7:44pm
(~18 anos atrás)
Muito bom este artigo!
Server de base para muitas outras organizações, uma vez que cada um tem a sua maneira de organizar seus códigos, mas sempre devem estar baseado (obedecendo)uma regra, e este está correto e simples, agora estou esperando a continuação do artigo, manda ver aí....
Inté + V.
Server de base para muitas outras organizações, uma vez que cada um tem a sua maneira de organizar seus códigos, mas sempre devem estar baseado (obedecendo)uma regra, e este está correto e simples, agora estou esperando a continuação do artigo, manda ver aí....
Inté + V.
09/05/2006 4:09pm
(~18 anos atrás)
Sua solução tem propósito, no entanto acho meio confuso criar toda uma nomenclatura só pra se saber o que o arquivo faz.
apps/
..../cadastros/
......../funcionario/
............/template/
................lista.tpl
................formulario.tpl
............/acao/
................listar.php
................inserir.php
................apagar.php
................atualizar.php
................editar.php
............index.php
css/
doc/
kernel/
image/
include/
js/
smarty/ (dentro além de classes do smarty vão templates globais)
sql/
config.php
define.php
Árvores variam mesmo de acordo com o gosto, no entanto quando se trata de gereciamento de operações dentro do módulo eu controlo através do index.php desviando o fluxo para a ação desejada.
Exemplo:
define('EDITAR',1);
define('XXXXXX',N); // "XXXXXX" nome da operação, "N" id da identificação
switch($op) {
case EDITAR: require 'acao/listar'; break;
case INSERIR: <instruções> break;
case ATUALIZAR: <instruções> break;
case APAGAR: <instruções> break;
default:
require 'acao/listar';
}
Não sei se é um bom exemplo, mas por enquanto tenho adotado esta maneira de trabalhar.
apps/
..../cadastros/
......../funcionario/
............/template/
................lista.tpl
................formulario.tpl
............/acao/
................listar.php
................inserir.php
................apagar.php
................atualizar.php
................editar.php
............index.php
css/
doc/
kernel/
image/
include/
js/
smarty/ (dentro além de classes do smarty vão templates globais)
sql/
config.php
define.php
Árvores variam mesmo de acordo com o gosto, no entanto quando se trata de gereciamento de operações dentro do módulo eu controlo através do index.php desviando o fluxo para a ação desejada.
Exemplo:
define('EDITAR',1);
define('XXXXXX',N); // "XXXXXX" nome da operação, "N" id da identificação
switch($op) {
case EDITAR: require 'acao/listar'; break;
case INSERIR: <instruções> break;
case ATUALIZAR: <instruções> break;
case APAGAR: <instruções> break;
default:
require 'acao/listar';
}
Não sei se é um bom exemplo, mas por enquanto tenho adotado esta maneira de trabalhar.
19/04/2006 9:16am
(~18 anos atrás)
Nota 10.
Como sempre nos surpreendendo em, venho a companhando seu trabalho a algum tempo, e em cada artigo, tenho aprendido mais.
Já apliquei este tipo de organização no sistema que estou desenvolvento, e facilitou bastante para trabalhar com os links de um arquivo para outro, eu criei uns script para fazer a verificação dos links de todos os arquivos, pois utilizo um unico arquivo contendo os links principais e o incluo nos outros arquivos do sistema, seguindo o seu esquema de organização os meu script de tratamento de links ficaram melhor organizados, estou fazendo a ultima verificação nos meus scripts para estar divulgando aqui pra galera.
Vi o Herbert Araujo comentando sobre a nomenclatura dos arquivos comuns. Talvez isso pode ajudar, a nomenclatura que adotei é a seguinte:
Arquivos: sis_frm_ins_user.php | sis_prg_ins_user.php | sis_insert_user.php
Onde:
-"sis" é a identificação do sistema;
-("frm" identifico que este arquivo é o formulário de cadastro;
-"prg" é o script que faz a validação dos campos vindos do fomulário);
-"ins" identifica o que este script ira fazer, neste caso inserir a informação no banco de dados;
-"user" identifica que tipo de informação será inclusa no banco;
-"insert" é o script que faz a inclusão no banco após satisfeitas todas as validação no script anterior {"prg"}.
Utilizo este mesmo esquema para as ações delete "del", update "upd" e pesquisa "sch". Caso esta não seja a melhor maniera aceito sugestões.
É isso ai continue com este excelente trabalho, sucessos.
Como sempre nos surpreendendo em, venho a companhando seu trabalho a algum tempo, e em cada artigo, tenho aprendido mais.
Já apliquei este tipo de organização no sistema que estou desenvolvento, e facilitou bastante para trabalhar com os links de um arquivo para outro, eu criei uns script para fazer a verificação dos links de todos os arquivos, pois utilizo um unico arquivo contendo os links principais e o incluo nos outros arquivos do sistema, seguindo o seu esquema de organização os meu script de tratamento de links ficaram melhor organizados, estou fazendo a ultima verificação nos meus scripts para estar divulgando aqui pra galera.
Vi o Herbert Araujo comentando sobre a nomenclatura dos arquivos comuns. Talvez isso pode ajudar, a nomenclatura que adotei é a seguinte:
Arquivos: sis_frm_ins_user.php | sis_prg_ins_user.php | sis_insert_user.php
Onde:
-"sis" é a identificação do sistema;
-("frm" identifico que este arquivo é o formulário de cadastro;
-"prg" é o script que faz a validação dos campos vindos do fomulário);
-"ins" identifica o que este script ira fazer, neste caso inserir a informação no banco de dados;
-"user" identifica que tipo de informação será inclusa no banco;
-"insert" é o script que faz a inclusão no banco após satisfeitas todas as validação no script anterior {"prg"}.
Utilizo este mesmo esquema para as ações delete "del", update "upd" e pesquisa "sch". Caso esta não seja a melhor maniera aceito sugestões.
É isso ai continue com este excelente trabalho, sucessos.
10/04/2006 8:36am
(~18 anos atrás)
Abraços