Coding Conventions - Web
Introdução
Este documento define a padronização para formatação de código fonte desenvolvidos para Web, além de expor algumas boas práticas que devem ser seguidas pelos desenvolvedores da Takenet.
Definições
Tipo de documento
Devemos definir no começo do html uma instrução para que o seu navegador saiba qual o tipo de documento. Segue alguns exemplos:
- <!-- HTML 5 -->>
<!DOCTYPE html>
- <!-- HTML 4.01 Strict -->>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> - <!-- XHTML 1.0 Strict -->>
<DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
Tags
Embora possa não apresentar problemas na interface, sempre que uma tag for aberta a mesma devera ser fechada. Você nunca vai saber como seu site irá sempre se comporta em diferentes navegadores, condições, tecnologias e se as normas não forem seguidas, será muito mais fácil para que os problemas ocorram.
HTML (HyperText Markup Language) não diferencia letras maiúsculas de minúsculas (case insensitive), mas isso não significa que devemos usar ambas. Para evitar mudança em todo o site e manter um padrão todas as tags devem ser com letras minúsculas.
Evitar o uso das tags: <br> <b> <center> <i> <font> <strong>, todas as tags que possam ser substituidas por definições no css.
<!-- Good -->
<h1> Heading</h1>
<p>some text.....</p>
<!-- Not so Good -->
<H1>Heading</h1>
<p>some text.....
Folhas de estilos externas (css)
O uso de folhas de estilos externas para declaração de propriedades css é uma das práticas que vem sendo ressaltada. Propriedades declaradas de forma “inline” dificultam a manutenção do website, deixam o código carregado de informações não relevantes para os mecanismos de busca e para os navegadores. Devido as declarações "inline" terem maior relevância na renderização realizada pelos navegadores, o que é declarado “inline” vai sobrescrever o que foi declarado nas folhas externas, fazendo com que você se obrigue a utilizar hacks, ou seja, um “conserto” atrás de outro.
Evitar o uso de marcações !Important no css assim como browser hacks. *{propriedade}.
É permitido a utilização de vendor specifics -moz -webkit mas optar sempre pela versão nativa.
Classes vs Id (css)
Você só deve dar atributos ID para um elemento se ele for único. Eles devem ser aplicados apenas para este elemento e mais nenhum outro. Classes podem ser aplicadas em múltiplos elementos quando estes compartilham as mesmas propriedades de estilo. Elementos que devem parecer e funcionar da mesma forma podem ter o mesmo nome de classe. Vale lembrar que o id deve ser sempre em camel Case, enquanto as classes devem ser spinal-case.
Nomeclaturas (css)
Prefira sempre dar nome a algo pela natureza do que é, ao invés do que ele parece, seja ele um ID ou uma classe. Por exemplo, um nome de classe bigBlueText para um nota especial em uma página é algo totalmente sem sentido porque se houver a necessidade de alterar para ter um texto menor com a cor vermelha o nome da classe perde a referência. Use uma convenção mais inteligente como noteText que é bem melhor, porque quando ocorrerem mudanças visuais, o nome continuará a fazer sentido.
Compatibilidade cross-browser
Os usuários hoje podem escolher entre uma grande variedade de navegadores web, cada um fornecendo uma ligeira (ou dramática) diferença na experiência do usuário. Como desenvolvedores, a nossa responsabilidade é escolher apenas como as páginas serão construídas e exibidas para aqueles usuários, suportando os diversos navegadores disponíveis no mercado.
Safari, IE 8+, Firefox, Chrome.
Javascript
Poderão ser utilizadas bibliotecas Javascript open-source populares, tais como JQuery, AngularJS, Dojo, D3js, dentro outras. Se estiver utilizando um template como Bootstrap, utiliza a biblioteca que o template suporta.
Considere utilizar Javascript "puro" para problemas simples, com intuito de melhorar o desempenho da aplicação do cliente.
Todas as variaveis Javascript devem ser notadas com camelCase, a única exceção para este caso é se estiver criando constructor functions, que devem ser PascalCase.
Se você tiver arquivos JavaScript que são exclusivamente para adicionar funcionalidades a uma página, é melhor colocá-lo no final do arquivo HTML, logo antes da tag BODY. Isso permitirá um processamento mais rápido da página.
Não incluir event listerners inline no HTML, inclua essas funcionalidades em um arquivo Javascript.
Otimizar Javascript/CSS
CSS e JavaScript devem estar minificados no lado do servidor.
CSS devem ser concatenados juntos. O objetivo principal é reduzir o número de conexões HTTP com dependências durante o carregamento da página.
Evite blocos <script> em linha com o HTML. Eles bloqueiam a renderização e são bastante devastadores com o tempo de carregamento de página.
Framework Front-end
Considere utilizar framework com template de layout como o Bootstrap, que ajudam a manter a consistência visual e agilizam o desenvolvimento. Manter design sempre responsivo utilizando o conceito mobile-first.
Favicon
Manter sempre um favicon.