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

Er Galvão Abbott – Especialista em TI – www.galvao.eti.br – galvao@galvao.eti.br

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.



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...................................................................................................................................2
Aviso.......................................................................................................................................2
Público-alvo............................................................................................................................3
Introdução..............................................................................................................................5
Exceções...........................................................................................................................5
Detalhamento.........................................................................................................................6
Conclusão............................................................................................................................18
Sobre 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

N/A
1. Versionamento
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.

N/A
2. Frameworks
Altamente 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.



N/A
3. Estrutura de Diretórios
Importâ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:

Illustration 1: Estrutura de diretórios

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.



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



N/A
4. Fases de Desenvolvimento
Importâ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:

Illustration 2: Fases de desenvolvimento/deployment

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.



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.

Todas
5. Indentação
Importâ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;
}



Todas
6. Nomenclatura

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



P J
7. Documentação de código-fonte
Importâ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



PHP
8. Sintaxe alternativa

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.

P J
9. Legibilidade – operadores e operandos
Menor 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) {
}



PHP
10. Legibilidade – Arrays complexos e queries SQL

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'”;

XHTML
11. Caracteres especiais e acentuação
Importâ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;



PHP
12. Usar type hinting/juggling

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 original
settype($_GET['id'], 'integer');

N/A
13. Foco nas consultas
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.



N/A
14. Modelagem

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.


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

Mais conteúdo relacionado

Mais procurados

Destaque

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

Mais de Er Galvão Abbott

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