Proposta de Boas Práticas e Padrões de Desenvolvimento Web

Er Galvão Abbott – Especialista em TI – www.galvao.eti.br – [email protected]

Proposta de Boas Práticas e Padrões de Desenvolvimento Web

CC Attribution-ShareAlike 3.0 Unported License by Er Galvão Abbott – 2011-01-13 – 1 / 19


Licença

Você é livre para compartilhar, adaptar e reproduzir esse material, contanto que as seguites condições sejam respeitadas:

• Atribuição: Você incluir a atribuição explicita ao autor deste documento, Er Galvão Abbott, com uma indicação para o seu site: http://www.galvao.eti.br/

• Licenciamento similar: Seu trabalho deve ser licenciado de forma igual ou similar a este, possiblitando que as pessoas distribuam e adaptem trabalhos derivados, com igual responsabilidade de Atribuição.

Quaisquer das condições acima pode ser liberada, através de permissão explícita e por escrito do Autor.

Aviso

Tudo o que este documento faz é sugerir boas práticas e padrões no desenvolvimento de aplicações web. O Autor não pode ser responsabilizado direta ou indiretamente, por nenhum problema criado pela adoção do que aqui é exposto, assim como não espera nenhuma forma de recompensa por melhorias que este documento venha a trazer.

Conforme exposto na introdução deste documento, o importante não é considerar nenhuma das sugestões aqui apresentadas como “a melhor forma de fazer”, mas sim a definição, clara e publicamente a disposição de toda a empresa, de padrões e boas práticas, bem como a disciplina por parte da equipe em seguí-las.

Além disso tome cuidado para não cair em uma “armadilha” comum: Não altere nenhum projeto atualmente em desenvolvimento ou já desenvolvido. Qualquer que seja o conjunto de boas práticas que sua empresa venha a adotar, acredite, ele só será viável se aplicado a partir de novos projetos.


http://www.galvao.eti.br/


Público-alvo

Este documento destina-se especificamente a profissionais do mercado de desenvolvimento de aplicações com interface web. Embora alguns tópicos sejam específicos para certas tecnologias ou linguagens (como Javascript e PHP), a maioria das propostas aqui apresentadas pode ser facilmente transposta em parte ou integralmente para tecnologias e linguagens diferentes.



Índice

Licença...................................................................................................................................2Aviso.......................................................................................................................................2Público-alvo............................................................................................................................3Introdução..............................................................................................................................5

Exceções...........................................................................................................................5Detalhamento.........................................................................................................................6Conclusão............................................................................................................................18Sobre o Autor.......................................................................................................................19



Introdução

Pergunte a qualquer membro de uma equipe de desenvolvimento web qual seria o pior cenário de trabalho possível. Entre várias respostas você perceberá uma quantidade grande de queixas em relação a trabalhar em projetos já existentes.

Por se tratar de um nicho muito novo de mercado o desenvolvimento web traz problemas derivados da falta de rotinas de trabalho bem definidas e padronizadas. Isto normalmente se traduz em aplicações que se tornam verdadeiros quebra-cabeças, com problemas que vão de códigos com diferenças estruturais gritantes a utilização de rotinas diferentes para solucionar problemas iguais, entre dezenas de outros.

Esta situação frequentemente leva os profissionais a realizarem um trabalho de formalização antes do trabalho propriamente dito. Isto causa um impacto considerável na execução das tarefas e termina por afetar o projeto no sentido de gerar atrasos nos prazos e um custo maior do que o alocado inicialmente no orçamento.

Se este trabalho extra solucionasse de fato o problema talvez estes atrasos e custos adicionais pudessem ser considerados aceitáveis, mas como esta formalização se dá com base em teorias particulares de cada membro da equipe e não se tornam padrão, o caos se mantém.

Este documento não se propõe a ser uma solução “mágica”, “nova” e muito menos “fácil”, mas uma série de rotinas e padrões sugeridos para serem debatidos, aceitos ou não e então definidos. É esta definição que representa a solução. Ela deve ser clara, estar disponível e ser apresentada a cada membro da equipe.

Exceções

Este documento propositalmente deixa de fora os tópicos Sistema Operacional e IDE:

Sistema Operacional é, geralmente escolha da empresa, enquanto que a IDE normalmente é escolha do desenvolvedor. É importante que essas características se mantenham porque no caso da empresa geralmente é uma questão de obrigatoriedade e para o desenvolvedor é hábito, agilidade e conforto.

Concluindo, são questões que, a não ser que conflitem com questões técnicas (o que raramente acontece), devem ser deixadas de lado.



Detalhamento

As boas práticas e padrões sugeridos neste documento utilizam basicamente duas formas de legenda: uma relativa a linguagem/teconologia a qual se aplica e outra que sugere a importância em aplicá-la o mais rápido possível, como demonstro a seguir:

PHP Javascript XHTML CSS Todas N/A

Table 1: Linguagens/Tecnologias

Importância Vital Altamente Recomendada Menor Importância

Table 2: Importância de implementação

1. VersionamentoN/A

Importância Vital

Versionamento deveria ser algo implícito em qualquer empresa de desenvolvimento, mas infelizmente as coisas não funcionam dessa forma. Todo e qualquer arquivo pertinente a um projeto deve ser, inequivocadamente, versionado. Tomo a liberdade de encerrar o assunto por aqui, certo de que os motivos específicos para se versionar arquivos/projetos sejam claros para qualquer empresa ou profissional.

2. Frameworks N/AAltamente Recomendada

Frameworks são extremamente importantes, pois não apenas facilitam o trabalho de organizar e padronizar o desenvolvimento, mas também tornam este trabalho mais fácil. É importante, entretanto, saber escolher um framework. Este deve possuir as seguintes características:

• Estabelecimento: Deve estar estabelecido há um tempo suficiente para inspirar confiança.

• Flexibilidade: Não deve limitar o desenvolvimento, ou seja: fatalmente terá suas regras de utilização, mas estas devem ser ou contornáveis ou aceitáveis.

• Ativo: Deve possuir um ciclo de desenvolvimento ativo, onde bugs e novas features são constantemente resolvidos/implementados.



3. Estrutura de Diretórios N/AImportância Vital

A estrutura de diretórios é vital na organização e estruturação de um projeto. Um dos equívocos mais comuns é tratar um projeto como simplesmente código-fonte e mais simplesmente ainda como uma pasta web. A estrutra de armazenamento de arquivos de um projeto deve prever mais do que isso, e não há razão – além de uma preocupação tola de que cada checkout inicial seja longo – pela qual todos os arquivos não devam ser versionados, mesmo os que são binários (como imagens, por exemplo). A seguir uma proposta de estrutura de diretórios, que não leva em conta a utilização de um framework:

Pontos vitais apresentados nesta estrutura:

• Todos os arquivos, sejam quais forem, estão previstos: É importante que cada membro da equipe possua sempre acesso total ao projeto. Embora seja possível argumentar que programadores, por exemplo, não teriam porque ter acesso a um determinado documento (Layouts, por exemplo), é sabido que na prática as coisas nem sempre são assim.

• Componentes “isolados”: Deve-se manter o que não é desenvolvido pela equipe (“externo”), isolado do que é (“interno”). Dessa forma pode-se não apenas controlar o versionamento de um componente específico dentro de um projeto (por exemplo, o ProjetoA usa a versão 1.3 da jquery), como encoraja-se a equipe a pensar e produzir em termos de generalização, produzindo eventualmente seus próprios componentes, que podem por sua vez ser utilizados em diversos projetos.


Illustration 1: Estrutura de diretórios


Isso nada mais é do que encorajar e alimentar um ciclo de desenvolvimento sadio dentro da empresa e da equipe.

• Raiz web (public_html): Outro ponto que deveria ser auto-explicativo, mas é comumente ignorado. A raiz web deve conter somente e tão somente arquivos que precisam ser acessados pelo browser e nada mais do que isso. Embora ignorar esse fato seja normalmente inofensivo, há relatos – para citar um exemplo – de pessoas que deixaram arquivos SQL disponíveis na raiz web, o que causou a indexação destes arquivos por mecanismos de busca e sua posterior exposição.

• Classes: Criar padrões baseados em nomenclatura de arquivos normalmente não funciona, por dois motivos. Primeiro, é uma tarefa tediosa ter que salvar cada arquivo seguindo um padrão, segundo pela simples razão de que é mais fácil, por exemplo, alguém esquecer de nomear um arquivo como “class.xxx.php” do que esquecer de salvar o arquivo no diretório “classes”.



4. Fases de Desenvolvimento N/AImportância Vital

Acostume-se a estruturar o processo de desenvolvimento em si. Embora haja n formas de fazê-lo, esta á proposta para as fases de desenvolvimento e deployment de uma aplicação:

1. Fase de Desenvolvimento: Cada desenvolvedor (D1, D2, Dn...) trabalha commitando sua produção em um repositório R. Testes preliminares e óbvios são realizados por cada desenvolvedor, para garantir uma qualidade mínima do trabalho executado. Quando chega-se a um ponto onde todos os desenvolvedores acreditam que seu trabalho está concluído chega-se às fases 2 e 3.

2. Code Freeze: Nesta fase todo e qualquer trabalho de desenvolvimento é suspenso e a aplicação é exportada de forma a se ter uma cópia funcional da mesma em um servidor (normalmente um servidor separado, mas não entrarei em tantos detalhes). É aí que se inicia a fase 3.

3. Testes: Com a aplicação em “suspenso” se iniciam os testes (p.ex.: testes unitários e testes de interface). É então gerado um relatório do que falhou nestes testes e retorna-se a fase 1 para a correção das falhas. Este caminho 1-2-3-1-2-3... deve ser “percorrido” quantas vezes forem necessárias.


Illustration 2: Fases de desenvolvimento/deployment


4. Produção: Com a certeza de que a aplicação passou por todos os testes e, obviamente, depois da aprovação do cliente, a aplicação entra, finalmente em produção.

5. Indentação TodasImportância Vital

Uma indentação correta é o padrão mínimo esperado de qualquer código-fonte dito profissional. Ela deve ser realizada com 4 espaços por nível e, ao contrário do que muitos pensam é aplicada à todas as linguagens. Exemplos de indentação:

• PHP:

if ($a > 0) { echo “A é maior do que 0”; if ($a < 2) { echo “ … e menor do que 2”; }}

• Javascript:

if (a == 0) { alert('a é igual a 0);}

• XHTML:

<div id=”foo”> <img src=”bar.png” /></div>

• CSS:

div#foo { font-family: sans-serif;}



6. Nomenclatura TodasAltamente Recomendada

Dois esclarecimentos se fazem necessários nesse item: primeiramente o importante aqui não é a criação de um padrão de nomenclatura, mas a utilização de um só padrão por arquivo. Além disso, é outro item em que nem sempre fica claro a sua utilização em certas linguagens, ao que segue:

• PHP: Variáveis, classes, métodos/funções...• Javascript: Variáveis, funções...• XHTML: Formulários, IDs de elementos, campos...• CSS: Classes. IDs...

O padrão se refere, especialmente, a separação de palavras, existindo basicamente duas formas de utilização:

• Underscore: minha_variavel• CamelCase: minhaVariavel



7. Documentação de código-fonte P JImportância Vital

A documentação de código-fonte deve implementar, no mínimo, o padrão PHPDoc. Desta forma não apenas pode-se produzir uma documentação técninca com a utilização de uma ferramenta como o PHPDocumentor, mas a própria utilização de classes, métodos e funções se torna mais intuitiva e menos confusa. Além disso, se torna menos provável a criação de componentes para resolver problemas já solucionados em um sistema, pois através desta documentação se tem um mapemento do que já foi desenvolvido.

Este item requer um certo cuidado, pois o excesso de documentação pode ser quase tão prejudicial quanto a sua falta. Não se deve documentar qualquer código-fonte, afinal de contas é documentar o óbvio torna todo o processo maçante e desencorajador.

Além disso, a linguagem Javascript atualmente tem um nível tão vital e complexo em um sistema que merece ser documentada da mesma forma. A seguir uma listagem das tags de documentação que considero relevantes:

• author• access• static• param• return• package• subpackage



8. Sintaxe alternativa PHPAltamente Recomendada

Por ser uma linguagem derivada em parte de Perl, PHP faz jus ao mote “TMTOWTDI – There's more than one to do it”. Isso, entretanto, nem sempre ajuda. Sintaxes alternativas costmam causar pelo menos um de dois problemas: ou elas são tão pouco utilizadas que até mesmo as IDEs as ignoram ou acabam por ser tão sintéticas que podem causar confusão na leitura do código-fonte.

Lembre-se: Este documento é formado de sugestões e é, inevitavelmente, opinativo. É minha opinião que ao invés de sintaxes alternativas como o operador ternário em caso de condicionais ou instruções que terminem em “end”, como endif devam ser evitadas.

O uso das formas contendo chaves de início e final auxiliam na compreensão do código-fonte, tornando o mais claro possível onde um bloco “subalterno” inicia e termina.

9. Legibilidade – operadores e operandos P JMenor Importância

Espaços em branco podem, muitas vezes, fazer toda a diferença quando se trata de legibilidade de código-fonte, e é minha opinião de que legibilidade é um assunto importantíssimo e que não deve ser menosprezado.

A inclusão de espaços em branco entre operandos e operadores melhora consideravelmente a legibilidade de um código-fonte, ou seja, ao invés de escrever:

if ($a!=1 and $b<8 and $c>=3) { }

procure escrever:

if ($a != 1 and $b < 8 and $c >= 3) { }



10. Legibilidade – Arrays complexos e queries SQL PHPAltamente Recomendada

Embora o excesso de cuidado com estilo de código-fonte possa se converter em uma atividade maçante, em certos casos específicos é um esforço que acaba valendo a pena. Isto é especialmente verdadeiro no caso de arrays e queries SQL complexos(as).

Como a maioria (senão todos) dos itens sobre legibilidade usamos basicamente os dois princípios mais importantes (espaçamento e indentalção) e isso fica mais claro ao apresentarmos exemplos.

Ex. 1 – Array:

$usuario = array('login' => 'foo', 'data_nascto' => array('dia' => 12, 'mes' => 1, 'ano' => 1973), 'nivel' => array('admin', 'usuario', 'fornecedor'));

---

$usuario = array( 'login' => 'foo', 'data_nascto' => array( 'dia' => 12, 'mes' => 1, 'ano' => 1973), 'nivel' => array( 'admin', 'usuario', 'fornecedor'));



Ex. 2 – Query:

$sql = “SELECT u.id FROM usuarios u, nivel n, nivel_usuarios nu WHERE login='foo' AND senha='bar' AND nu.usuario_id = u.id AND nu.nivel_id = n.id AND n.nome='admin'”;

---

$sql = “SELECT u.id FROM usuarios u, nivel n, nivel_usuarios nu WHERE u.login='foo' AND u.senha='bar' AND nu.usuario_id = u.id AND nu.nivel_id = n.id AND n.nome='admin'”;

11. Caracteres especiais e acentuação XHTMLImportância Vital

Crie o hábito de utilizar entidades XHTML. Elas não apenas asseguram que o conteúdo será exibido propriamente, como impede a “truncagem” de caracteres. Alguns exemplos:

• á → á• ô → ô• & → &

Além disso, uma dica adicional: procure utilizar UTF-8 como a codificação padrão, tanto em sua tag XHTML meta, como na base de dados. UTF-8 vêm se tornando a codificação padrão para aplicações web.

Exemplos:

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

CREATE DATABASE foo CHARACTER SET=utf8;



12. Usar type hinting/juggling PHPAltamente Recomendada

Programação tem tudo a ver com atenção aos detalhes e controlar o máximo possível o que pode ser controlado. Embora a maior parte (senão todas) das tecnologias web seja tipada dinamicamente, no caso do PHP a tipagem pode ser facilmente forçada. Se certificar de que um dado seja do tipo esperado não é apenas uma boa prática, mas também uma questão de segurança.

Exemplos:

// Forçando a tipagem em tempo de execução:$id = (int)$_GET['id'];

// Forçando a tipagem efetivamente, modificando o tipo originalsettype($_GET['id'], 'integer');

13. Foco nas consultasN/A

Importância Vital

Consultas a dados devem retornar apenas o necessário. Retornar vinte colunas para utilizar apenas duas informações não apenas afeta a aplicação como um todo em questão de performance, mas pode contribuir para situações que variam desde a negação de requisições ao vazamento de informações.



14. Modelagem N/AAltamente Recomendada

A padronização da modelagem de dados não apenas mantém a aplicação organizada, mas torna intuitivo, chegando a dispensar o modelo ER (que de qualquer forma deve ser obrigatório) na hora de programar.

Padronização sugerida:

• Entidades: Nome, no plural. Exemplos: usuarios, clientes• Chaves Primárias: apenas o termo id. Colocar o nome da entidade na PK não

apenas é desnecessário, mas torna o uso da coluna extremamente cansativo.• Chaves Estrangeiras: Nome da entidade de origem no singular + '_id'.

Exemplos: usuario_id, cliente_id• Entidades que representam relações M:N: entidades no plural, em ordem

alfabetica, separadas por underscore. Exemplos: compras_produtos, usuarios_niveis



Conclusão

A criação de uma padronização no desenvolvimento web tem um impacto positivo enorme nos processos de desenvolvimento de aplicações, além de atenuar a manutenção de aplicações pré-existentes, mas não se trata. obviamente de uma solução “mágica”.

Disciplina e verificação constante do respeito aos padrões adquiridos são condições obrigatórias para que as coisas funcionem como esperado. Após algum tempo de utilização, contudo, estes padrões acabam se tornando hábitos e a possibilidade de trangressão se torna muito menor.

As vantagens em sua adoção contudo são permanentes, e a ordem estabelecida torna o trabalho de todos muito mais fácil, chegando a ter influências positivas tão distintas como a melhoria do ânimo da equipe, a facilidade de localização de característiicas específicas de um sistema e a diminuição no tempo total de desenvolvimento de uma aplicação.



Sobre o Autor

Er Galvão Abbott trabalha há mais de 15 anos com o desenvolvimento de aplicações com interface web. Palestrante nos principais eventos nacionais, ministra cursos e é ativo nas comunidades Open Source e de PHP.

É Diretor Geral da PHP Conference Brasil, o principal evento de PHP da América Latina e colabora na organização do Fórum de Software Livre de Curitiba.

Especializou-se em segurança de aplicações web, sendo um dos primeiros profissionais brasileiros a abordar o assunto se tratando especificamente da linguagem PHP.


http://www.phpconference.com.br/

Self Improvement

Proposta de Boas Práticas e Padrões de Desenvolvimento Web