Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.

br

Proposta de Boas Prticas e

Padres de Desenvolvimento Web

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 1 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

Licena
Voc livre para compartilhar, adaptar e reproduzir esse material, contanto que as
seguites condies sejam respeitadas:

Atribuio: Voc incluir a atribuio explicita ao autor deste documento, Er Galvo

Abbott, com uma indicao 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 Atribuio.

Quaisquer das condies acima pode ser liberada, atravs de permisso explcita e
por escrito do Autor.

Aviso
Tudo o que este documento faz sugerir boas prticas e padres no
desenvolvimento de aplicaes web. O Autor no pode ser responsabilizado direta ou
indiretamente, por nenhum problema criado pela adoo do que aqui exposto, assim
como no espera nenhuma forma de recompensa por melhorias que este documento
venha a trazer.
Conforme exposto na introduo deste documento, o importante no considerar
nenhuma das sugestes aqui apresentadas como a melhor forma de fazer, mas sim a
definio, clara e publicamente a disposio de toda a empresa, de padres e boas
prticas, bem como a disciplina por parte da equipe em segu-las.
Alm disso tome cuidado para no cair em uma armadilha comum: No altere
nenhum projeto atualmente em desenvolvimento ou j desenvolvido. Qualquer que seja o
conjunto de boas prticas que sua empresa venha a adotar, acredite, ele s ser vivel se
aplicado a partir de novos projetos.

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 2 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

Pblico-alvo
Este documento destina-se especificamente a profissionais do mercado de
desenvolvimento de aplicaes com interface web. Embora alguns tpicos sejam
especficos 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.

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 3 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

ndice
Licena...................................................................................................................................2
Aviso.......................................................................................................................................2
Pblico-alvo............................................................................................................................3
Introduo..............................................................................................................................5
Excees...........................................................................................................................5
Detalhamento.........................................................................................................................6
Concluso............................................................................................................................18
Sobre o Autor.......................................................................................................................19

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 4 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

Introduo
Pergunte a qualquer membro de uma equipe de desenvolvimento web qual seria o
pior cenrio de trabalho possvel. Entre vrias respostas voc perceber uma quantidade
grande de queixas em relao 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 aplicaes que se tornam verdadeiros quebra-cabeas, com
problemas que vo de cdigos com diferenas estruturais gritantes a utilizao de rotinas
diferentes para solucionar problemas iguais, entre dezenas de outros.
Esta situao frequentemente leva os profissionais a realizarem um trabalho de
formalizao antes do trabalho propriamente dito. Isto causa um impacto considervel na
execuo 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 oramento.
Se este trabalho extra solucionasse de fato o problema talvez estes atrasos e
custos adicionais pudessem ser considerados aceitveis, mas como esta formalizao se
d com base em teorias particulares de cada membro da equipe e no se tornam padro,
o caos se mantm.
Este documento no se prope a ser uma soluo mgica, nova e muito menos
fcil, mas uma srie de rotinas e padres sugeridos para serem debatidos, aceitos ou
no e ento definidos. esta definio que representa a soluo. Ela deve ser clara, estar
disponvel e ser apresentada a cada membro da equipe.

Excees
Este documento propositalmente deixa de fora os tpicos Sistema Operacional e
IDE:
Sistema Operacional , geralmente escolha da empresa, enquanto que a IDE
normalmente escolha do desenvolvedor. importante que essas caractersticas se
mantenham porque no caso da empresa geralmente uma questo de obrigatoriedade e
para o desenvolvedor hbito, agilidade e conforto.
Concluindo, so questes que, a no ser que conflitem com questes tcnicas (o
que raramente acontece), devem ser deixadas de lado.
CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 5 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

Detalhamento
As boas prticas e padres sugeridos neste documento utilizam basicamente duas
formas de legenda: uma relativa a linguagem/teconologia a qual se aplica e outra que
sugere a importncia em aplic-la o mais rpido possvel, como demonstro a seguir:
PHP

Javascript

XHTML

CSS

Todas

N/A

Table 1: Linguagens/Tecnologias
Importncia Vital

Altamente Recomendada

Menor Importncia

Table 2: Importncia de implementao

1. Versionamento

N/A
Importncia Vital

Versionamento deveria ser algo implcito em qualquer empresa de desenvolvimento,

mas infelizmente as coisas no 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 especficos para se versionar
arquivos/projetos sejam claros para qualquer empresa ou profissional.
2. Frameworks

N/A
Altamente Recomendada

Frameworks so extremamente importantes, pois no apenas facilitam o trabalho de

organizar e padronizar o desenvolvimento, mas tambm tornam este trabalho mais fcil.
importante, entretanto, saber escolher um framework. Este deve possuir as seguintes
caractersticas:

Estabelecimento: Deve estar estabelecido h um tempo suficiente para inspirar

confiana.
Flexibilidade: No deve limitar o desenvolvimento, ou seja: fatalmente ter suas
regras de utilizao, mas estas devem ser ou contornveis ou aceitveis.
Ativo: Deve possuir um ciclo de desenvolvimento ativo, onde bugs e novas features
so constantemente resolvidos/implementados.

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 6 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

3. Estrutura de Diretrios

N/A
Importncia Vital

A estrutura de diretrios vital na organizao e estruturao de um projeto. Um dos

equvocos mais comuns tratar um projeto como simplesmente cdigo-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 no h razo alm de uma preocupao tola
de que cada checkout inicial seja longo pela qual todos os arquivos no devam ser
versionados, mesmo os que so binrios (como imagens, por exemplo).
A seguir uma proposta de estrutura de diretrios, que no leva em conta a utilizao de
um framework:

Illustration 1: Estrutura de diretrios

Pontos vitais apresentados nesta estrutura:

Todos os arquivos, sejam quais forem, esto previstos: importante que cada
membro da equipe possua sempre acesso total ao projeto. Embora seja possvel
argumentar que programadores, por exemplo, no teriam porque ter acesso a um
determinado documento (Layouts, por exemplo), sabido que na prtica as coisas
nem sempre so assim.

Componentes isolados: Deve-se manter o que no desenvolvido pela equipe

(externo), isolado do que (interno). Dessa forma pode-se no apenas controlar
o versionamento de um componente especfico dentro de um projeto (por exemplo,
o ProjetoA usa a verso 1.3 da jquery), como encoraja-se a equipe a pensar e
produzir em termos de generalizao, produzindo eventualmente seus prprios
componentes, que podem por sua vez ser utilizados em diversos projetos.
CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 7 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

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 to 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 disponveis na raiz web, o que causou a
indexao destes arquivos por mecanismos de busca e sua posterior exposio.

Classes: Criar padres baseados em nomenclatura de arquivos normalmente no

funciona, por dois motivos. Primeiro, uma tarefa tediosa ter que salvar cada
arquivo seguindo um padro, segundo pela simples razo de que mais fcil, por
exemplo, algum esquecer de nomear um arquivo como class.xxx.php do que
esquecer de salvar o arquivo no diretrio classes.

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 8 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

4. Fases de Desenvolvimento

N/A
Importncia 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
aplicao:

Illustration 2: Fases de desenvolvimento/deployment

1. Fase de Desenvolvimento: Cada desenvolvedor (D1, D2, Dn...) trabalha
commitando sua produo em um repositrio R. Testes preliminares e bvios so
realizados por cada desenvolvedor, para garantir uma qualidade mnima do
trabalho executado. Quando chega-se a um ponto onde todos os desenvolvedores
acreditam que seu trabalho est concludo chega-se s fases 2 e 3.
2. Code Freeze: Nesta fase todo e qualquer trabalho de desenvolvimento suspenso
e a aplicao exportada de forma a se ter uma cpia funcional da mesma em um
servidor (normalmente um servidor separado, mas no entrarei em tantos
detalhes). a que se inicia a fase 3.
3. Testes: Com a aplicao em suspenso se iniciam os testes (p.ex.: testes unitrios
e testes de interface). ento gerado um relatrio do que falhou nestes testes e
retorna-se a fase 1 para a correo das falhas. Este caminho 1-2-3-1-2-3... deve
ser percorrido quantas vezes forem necessrias.

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 9 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

4. Produo: Com a certeza de que a aplicao passou por todos os testes e,

obviamente, depois da aprovao do cliente, a aplicao entra, finalmente em
produo.
5. Indentao

Todas
Importncia Vital

Uma indentao correta o padro mnimo esperado de qualquer cdigo-fonte dito

profissional. Ela deve ser realizada com 4 espaos por nvel e, ao contrrio do que muitos
pensam aplicada todas as linguagens. Exemplos de indentao:

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;
}

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 10 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

6. Nomenclatura

Todas
Altamente Recomendada

Dois esclarecimentos se fazem necessrios nesse item: primeiramente o importante

aqui no a criao de um padro de nomenclatura, mas a utilizao de um s padro
por arquivo. Alm disso, outro item em que nem sempre fica claro a sua utilizao em
certas linguagens, ao que segue:

PHP: Variveis, classes, mtodos/funes...

Javascript: Variveis, funes...
XHTML: Formulrios, IDs de elementos, campos...
CSS: Classes. IDs...

O padro se refere, especialmente, a separao de palavras, existindo basicamente

duas formas de utilizao:

Underscore: minha_variavel
CamelCase: minhaVariavel

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 11 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

7. Documentao de cdigo-fonte

P
J
Importncia Vital

A documentao de cdigo-fonte deve implementar, no mnimo, o padro PHPDoc.

Desta forma no apenas pode-se produzir uma documentao tcninca com a utilizao
de uma ferramenta como o PHPDocumentor, mas a prpria utilizao de classes,
mtodos e funes se torna mais intuitiva e menos confusa. Alm disso, se torna menos
provvel a criao de componentes para resolver problemas j solucionados em um
sistema, pois atravs desta documentao se tem um mapemento do que j foi
desenvolvido.
Este item requer um certo cuidado, pois o excesso de documentao pode ser quase
to prejudicial quanto a sua falta. No se deve documentar qualquer cdigo-fonte, afinal
de contas documentar o bvio torna todo o processo maante e desencorajador.
Alm disso, a linguagem Javascript atualmente tem um nvel to vital e complexo em
um sistema que merece ser documentada da mesma forma. A seguir uma listagem das
tags de documentao que considero relevantes:

author
access
static
param
return
package
subpackage

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 12 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

8. Sintaxe alternativa

PHP
Altamente 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 so to pouco utilizadas que
at mesmo as IDEs as ignoram ou acabam por ser to sintticas que podem causar
confuso na leitura do cdigo-fonte.
Lembre-se: Este documento formado de sugestes e , inevitavelmente, opinativo.
minha opinio que ao invs de sintaxes alternativas como o operador ternrio em caso de
condicionais ou instrues que terminem em end, como endif devam ser evitadas.
O uso das formas contendo chaves de incio e final auxiliam na compreenso do
cdigo-fonte, tornando o mais claro possvel onde um bloco subalterno inicia e termina.
9. Legibilidade operadores e operandos

P
J
Menor Importncia

Espaos em branco podem, muitas vezes, fazer toda a diferena quando se trata de
legibilidade de cdigo-fonte, e minha opinio de que legibilidade um assunto
importantssimo e que no deve ser menosprezado.
A incluso de espaos em branco entre operandos e operadores melhora
consideravelmente a legibilidade de um cdigo-fonte, ou seja, ao invs de escrever:
if ($a!=1 and $b<8 and $c>=3) {
}
procure escrever:
if ($a != 1 and $b < 8 and $c >= 3) {
}

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 13 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

10. Legibilidade Arrays complexos e queries SQL

PHP
Altamente Recomendada

Embora o excesso de cuidado com estilo de cdigo-fonte possa se converter em uma

atividade maante, em certos casos especficos um esforo que acaba valendo a pena.
Isto especialmente verdadeiro no caso de arrays e queries SQL complexos(as).
Como a maioria (seno todos) dos itens sobre legibilidade usamos basicamente os dois
princpios mais importantes (espaamento e indentalo) 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')
);

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 14 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

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 acentuao

XHTML
Importncia Vital

Crie o hbito de utilizar entidades XHTML. Elas no apenas asseguram que o contedo
ser exibido propriamente, como impede a truncagem de caracteres. Alguns exemplos:

&aacute;
&ocirc;
& &amp;

Alm disso, uma dica adicional: procure utilizar UTF-8 como a codificao padro, tanto
em sua tag XHTML meta, como na base de dados. UTF-8 vm se tornando a codificao
padro para aplicaes web.
Exemplos:
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
CREATE DATABASE foo CHARACTER SET=utf8;
CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 15 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

12. Usar type hinting/juggling

PHP
Altamente Recomendada

Programao tem tudo a ver com ateno aos detalhes e controlar o mximo possvel o
que pode ser controlado. Embora a maior parte (seno todas) das tecnologias web seja
tipada dinamicamente, no caso do PHP a tipagem pode ser facilmente forada. Se
certificar de que um dado seja do tipo esperado no apenas uma boa prtica, mas
tambm uma questo de segurana.
Exemplos:
// Forando a tipagem em tempo de execuo:
$id = (int)$_GET['id'];
// Forando a tipagem efetivamente, modificando o tipo original
settype($_GET['id'], 'integer');
13. Foco nas consultas

N/A
Importncia Vital

Consultas a dados devem retornar apenas o necessrio. Retornar vinte colunas para
utilizar apenas duas informaes no apenas afeta a aplicao como um todo em questo
de performance, mas pode contribuir para situaes que variam desde a negao de
requisies ao vazamento de informaes.

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 16 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

14. Modelagem

N/A
Altamente Recomendada

A padronizao da modelagem de dados no apenas mantm a aplicao organizada,

mas torna intuitivo, chegando a dispensar o modelo ER (que de qualquer forma deve
ser obrigatrio) na hora de programar.
Padronizao sugerida:

Entidades: Nome, no plural. Exemplos: usuarios, clientes

Chaves Primrias: apenas o termo id. Colocar o nome da entidade na PK no
apenas desnecessrio, 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 relaes M:N: entidades no plural, em ordem
alfabetica, separadas por underscore. Exemplos: compras_produtos,
usuarios_niveis

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 17 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

Concluso
A criao de uma padronizao no desenvolvimento web tem um impacto positivo
enorme nos processos de desenvolvimento de aplicaes, alm de atenuar a manuteno
de aplicaes pr-existentes, mas no se trata. obviamente de uma soluo mgica.
Disciplina e verificao constante do respeito aos padres adquiridos so
condies obrigatrias para que as coisas funcionem como esperado. Aps algum tempo
de utilizao, contudo, estes padres acabam se tornando hbitos e a possibilidade de
trangresso se torna muito menor.
As vantagens em sua adoo contudo so permanentes, e a ordem estabelecida
torna o trabalho de todos muito mais fcil, chegando a ter influncias positivas to
distintas como a melhoria do nimo da equipe, a facilidade de localizao de
caracterstiicas especficas de um sistema e a diminuio no tempo total de
desenvolvimento de uma aplicao.

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 18 / 19

Er Galvo Abbott Especialista em TI www.galvao.eti.br galvao@galvao.eti.br

Sobre o Autor
Er Galvo Abbott trabalha h mais de 15 anos com o
desenvolvimento de aplicaes 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 Amrica Latina e colabora na organizao do Frum
de Software Livre de Curitiba.
Especializou-se em segurana de aplicaes web, sendo um
dos primeiros profissionais brasileiros a abordar o assunto se
tratando especificamente da linguagem PHP.

CC Attribution-ShareAlike 3.0 Unported License by Er Galvo Abbott 2011-01-13 19 / 19