Esse é um styleguide para boas práticas de front-end.
O objetivo disso é ter documentado algumas práticas para um desenvolvimento consistente, legível e funcional. Para servir de consulta a desenvolvedores antigos e ajuda aos novos. Aqui não encontra-se a verdade absoluta, apenas um apurado de todo o conteúdo disponível e que foram considerados um bom modelo.
O conteúdo foi retirado da web e pertence exclusivamente a seus criadores citados nos créditos.
Por favor, Contribua.
Todo código em qualquer aplicação deve parecer como se tivesse sido escrito por uma única pessoa, independentemente de quantas pessoas tenham contribuído.
- Geral
- HTML
- CSS
- JS
Todo código em qualquer aplicação deve parecer como se tivesse sido escrito por uma única pessoa, independentemente de quantas pessoas tenham contribuído.
Omitir o protocolo (http:, https:) das URLs das imagens, midias, style sheets, scripts que estão disponíveis em ambos protocolos.
Omitir o protocolo torna a "URL relativa", evitando problemas de conteúdo misto.
Não Recomendado:
<script src="http://www.meusite.com/js/main.js"></script>
.example {
background: url('http://www.meusite.com/img/bg-body.jpg');
}
Recomendado:
<script src="//www.meusite.com/js/main.js"></script>
.example {
background: url('//www.meusite.com/img/bg-body.jpg');
}
Ainda melhor se for possível declarar dessa maneira:
<script src="js/main.js"></script>
.example {
background: url('../img/bg-body.jpg');
}
Apenas um estilo deve existir em todo o projeto. Seja sempre consistente na utilização da indentação para melhorar a legibilidade.
Escolha entre indentação suave (espaços) ou tabulação. Atenha-se à sua escolha sem falhar. (Recomendado: espaços) Se usar espaços, escolha o número de caracteres usados por nível de indentação. (Recomendado: 4 espaços)
Nunca misture espaços e tabs para indentação.
Dica: configure seu editor para mostrar "caractéres invisíveis". Isso irá permitir que você elimine espaços em branco da quebra de linha evitando commits poluídos.
Dica: use um EditorConfig arquivo (ou equivalente) para ajudar a manter a convenção básica de indentação que você aceitou para sua base de código.
<ul>
<li>Exemplo</li>
<li>Indentado</li>
</ul>
.exemplo {
color: blue;
}
Sempre use minúsculo.
Todo o código deve estar em letras minúsculas: Isso se aplica a nomes de elementos HTML, atributos, valores de atributos (exceto text/CDATA), seletores CSS, propriedades e valores de propriedade (com exceção de strings).
Não recomendado:
<A HREF="/">Home</A>
.example {
COLOR: #E5E5E5;
}
Recomendado:
<img src="google.png" alt="Google">
.example {
color: #e5e5e5;
}
Remova os espaços em branco, eles são desnecessários e podem complicar o uso de ferramentas de diff.
Não recomendado:
<p>Lorem ipsum. </p>
Recomendado:
<p>Lorem ipsum.</p>
Use UTF-8 (sem BOM).
Verifique se o seu editor usa UTF-8 (sem BOM) como codificação de caracteres.
Especifique a codificação em arquivos HTML via <meta charset="utf-8">
.
Comente o código quando achar necessário, seja cauteloso, o excesso também pode prejudicar.
Isso dependerá da complexidade do projeto.
Aplicações devem ser escritas em um único idioma, não importe o idioma que seja.
Se você deseja que sua aplicação tenha apoio de outros desenvolvedores desconhecidos é recomendável que opte pelo idioma Inglês.
Sempre tenha páginas de erro para seu projeto ou forneça algum fallback para o usuário.
É recomendado ao menos fornecer a página de erro 404 (Página não encontrada).
Use HTML5 sempre!
A sintax HTML5 deve ser definida em todos os documentos HTML usando:
<!DOCTYPE html>
Para uma melhor organização e suporte da sua aplicação, utilize a notação abaixo, com ela você fornecerá fallback a navegadores antigos mais facilmente.
<!DOCTYPE html>
<!--[if lt IE 7]> <html lang="pt-BR" class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[if IE 7]> <html lang="pt-BR" class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html lang="pt-BR" class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html lang="pt-BR" class="no-js"> <!--<![endif]-->
Não feche elementos nulos, ou seja, use <img>
, <link>
, etc.. E não <img />
, <link />
.
Use HTML validado sempre que possível.
Use ferramentas como o W3C HTML validator para teste.
Não recomendado:
<span>
<ul>
<a href="#">Lorem ipsum</a>
<br>
<a href="#">Lorem ipsum</a>
</ul>
</span>
Recomendado:
<div>
<ul>
<li>Lorem ipsum</li>
<li>Lorem ipsum</li>
<li>Lorem ipsum</li>
</ul>
<p>Lorem ipsum sit amet</p>
</div>
Use HMTL de acordo com seu propósito.
- Use os elementos ("tags") para o objetivo que eles foram criados. Por exemplo, use
<h1>
,<h2>
,<h3>
,<h4>
,<h5>
,<h6>
para cabeçalhos ou itens importantes,<p>
para parágrafos,<a>
para âncoras, etc. - Cada parágrafo deve estar dentro de uma tag
<p>
. Nunca use<br/>
para criar multiplos parágrafos. - Itens em forma de lista sempre devem estar dentro de
<ul>
,<ol>
, ou<dl>
, Nunca use<div>
ou<p>
. - Cada texto atrelado a um input de formulário deve utilizar a tag
<label>
. Especialmente elementos radio ou checkbox. - Mesmo que usar aspas duplas (" ") em atributos seja opcional, sempre as declare para tornar o código mais legível.
- Sempre declare um
<title></title>
para cada página.
Usar HTML de acordo com seu propósito é importante para semântica, acessibilidade, reúso, e código eficiente.
Não recomendado:
<div onclick="goToContact();">Contato</div>
Recomendado:
<a href="/contato" title="Contato">Contato</a>
Forneça alternativas para conteúdos multimídia.
Para mídias, como imagens, videos, objetos animados via canvas, tenha certeza de oferecer alternativas de acesso. Para imagens use alt=""
e title=""
e para videos e audios use legendas ou texto, se disponíveis.
Não recomendado:
<img src="logotipo.png">
Recomendado:
<img src="logotipo.png" alt="Empresa FooBar" title="Empresa FooBar">
Separe a estrutura da apresentação e do comportamento.
Separe estritamente a estrutura (markup), apresentação/estilo (style sheet), e comportamento (scripts), mantendo eles cada um no seu arquivo mas com as suas interações.
Separar a estrutura da apresentação e comportamento é muito importante por motivos de manutenção.
É sempre mais custoso para alterar documentos que não estão bem estruturados.
Não recomendado:
<!DOCTYPE html>
<html>
<head>
<title>HTML sucks</title>
<style>
body {
background-color: #888;
color: #fff;
}
</style>
<script>
alert('HTML sucks!!!!!');
</script>
</head>
<body>
<h1 style="font-size: 20px;">HTML Sucks</h1>
<p style="font-size: 10px; color: #333; margin: 0 15px 10px;">Lorem ipsum dolor</p>
<h2 padding-top: 40px; color: red;>HTML is stupid!!1</h2>
<center>Lorem ipsum dolor sit amet, consectetur adipisicing elit</center>
</body>
</html>
Recomendado:
<!DOCTYPE html>
<html>
<head>
<title>My first CSS-only redesign</title>
<link rel="stylesheet" href="css/main.css">
</head>
<body>
<h1>My first CSS-only redesign</h1>
<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit.</p>
<h2>It's awesome!</h2>
<script src="js/main.js"></script>
</body>
</html>
Não use entity references.
Não é necessário utilizar entity references como —
, ”
, ou ☺
, assumindo que você está utilizando codificação UTF-8.
As únicas exceções se aplicam a caracteres com significado especial para o HTML (como <
e &
), bem como caracteres "invisíveis" (como
).
Não recomendado:
O simbolo atual para o Euro é “&eur;”
.
Recomendado:
O simbolo atual para o Euro é €
.
Omita o tipo type=""
para as folhas de estilo e scripts.
Não use o atributo type para folhas de estilo (a não ser que não usar CSS) e scripts (a não ser que não usar JavaScript).
Não é necessário especificá-los, o HTML5 tem como padrão text/css
para folhas de estilos e text/javascript
para scripts.
Isso pode ser feito com segurança, mesmo para navegadores mais antigos.
Não recomendado:
<link type="text/css" rel="stylesheet" href="//www.google.com/css/maia.css">
<script type="text/javascript" src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
Recomendado:
<link rel="stylesheet" href="//www.google.com/css/maia.css">
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
Use uma nova linha para cada elemento block, list ou table, e indente todos seus elementos filhos.
Independente do estilo de um elemento (o CSS permite que aos elementos assumir um papel diferente através da propriedade display), coloque cada elemento block, list ou table em uma nova linha.
Também indente mesmo que sejam filhos de outro elemento block, list ou table.
<blockquote>
<p><em>Space</em>, the final frontier.</p>
</blockquote>
<ul>
<li>Moe</li>
<li>Larry</li>
<li>Curly</li>
</ul>
<h1>HTML Rocks!</h1>
<table>
<thead>
<tr>
<th scope="col">Income</th>
<th scope="col">Taxes</th>
</tr>
</thead>
<tbody>
<tr>
<td>$ 5.00</td>
<td>$ 4.50</td>
</tr>
</tbody>
</table>
Sempre use aspas duplas no arquivo html.
Use aspas duplas (" ") ao invés de simples (' ').
Use (' ') para JavaScript e CSS.
Não recomendado:
<a class='bt bt-primary'>Login</a>
Recomendado:
<a class="bt bt-primary">Login</a>
Use CSS válidado sempre que possível. Pois isso também pode ajudar a garantir a qualidade do seu código.
Use nomes significantes e genéricos para classes e IDs.
Em vez de nomes descritivos ou enigmáticos, sempre use nomes que refletem o propósito do elemento em questão, ou que são de maneira genérica.
O uso de nomes funcionais e genéricos reduz a probabilidade de documentação desnecessária e mudanças na estrutura.
Além disso, a prática de nomes genéricos é melhor, pois sendo muito específico toda vez que o layout precisar ser alterado você precisará mudar o nome do(a) ID/classe se for muito específico e não condizer com o novo layout.
Não recomendado:
#navigation {} /* Nomeclatura extensa desnecessária. */
.bt-verde-maior {} /* Classe usada somente para um botão verde grande. */
.bt-green {} /* Fixada a cor verde, caso precisar mudar a cor, precisará trocar a classe, alterando o html. */
#login-area {} /* Nome composto sem necessidade. */
#left-bar {} /* Fixado que é uma barra no lado esquerdo, se for preciso mudar para o lado direito precisará alterar o html. */
.images-lists {} /* Somente imagens. */
Recomendado:
#nav {} /* Nomeclatura simples, sem perder o sentido. */
.bt-secondary {} /* Um botão diferente do botão padrão. */
.bt-big {} /* Contém propriedades para aumentar o tamanho padrao de .bt */
#login {} /* Area de login. */
#sidebar {} /* Barra lateral. */
.gallery {} /* Pode ser galeria de imagens, videos, audio. */
Separe as palavras em IDs e Classes com um "-".
Não concatene palavras em um seletor.
Ter um padrão definido ajuda para não haver nomes conflitando e em manutenções.
Não recomendado:
#videoid
.bt_big
.titlePage
Recomendado:
#video-id
.bt-big
.title-page
Evite utilizar tipos de seletores em IDs e Classes.
A menos que seja necessário, sempre deve evitar essa prática.
Evitando seletores ancestrais desnecessários também ajudará na performance do seu site.
Não recomendado:
ul#products {}
h2.title-page {}
div.error {}
Recomendado:
#products {}
.title-page {}
.error {}
Algumas propriedades do CSS podem ser combinadas em formas abreviadas.
Não recomendado:
selector {
border-top-style: none;
font-family: Arial, tahoma, sans-serif;
font-size: 16px;
line-height: 1.4;
padding-top: 0;
padding-bottom: 10px;
padding-left: 5px;
padding-right: 5px;
}
Recomendado:
selector {
border-top: 0;
font: 16px/1.4 Arial, tahoma, sans-serif;
padding: 0 5px 10px;
}
Omita a especificação da unidade quando o valor for "0".
Pois zero é zero em qualquer unidade, então é desnecessária essa informação.
Não recomendado:
margin: 0px;
Recomendado:
padding: 0;
border: 0;
Omita o "0" na frente de valores entre -1 e 1, não é necessário.
font-size: .8em;
opacity: .5;
se 3 characteres hexadecimais quando possível.
Para cores isso é permitido, 3 characteres hexadecimais é melhor para digitar e mais sucinto.
Não recomendado:
color: #eebbcc;
background-color: #666666;
Recomendado:
color: #ebc;
background-color: #666;
Não utilize CSS Hacks!
Essa é uma prática muito ruim e pode gerar algumas complicações.
Utilize uma abordagem diferente com fallbacks, seja utilizando o Modernizr ou com a declaração de navegadores antigos no comentário do início da página.
Não recomendado
selectior {
margin: 50px;
_margin: 25px;
}
Recomendado:
.no-csstransitions seletor { ... }
.lt-ie9 seletor { ... }
Código bem comentado é extremamente importante. Tire tempo para descrever componentes, como eles funcionam, suas limitações, e o modo como são construídos. Não deixe outros no time adivinharem o propósito de códigos incomuns ou não óbvios.
Estilo de comentário deve ser simples e consistente dentro de uma única base de código.
- Coloque comentários em uma nova linha acima do seu assunto.
- Evite comentários no fim da linha.
- Mantenha o comprimento da linha a um máximo sensível, por exemplo, 80 colunas.
- Faça o uso liberal de comentários para quebrar o código CSS em seções distintas.
- Use comentários com iniciais maiúsculas e indentação de texto consistente.
- Dica: configure seu editor para lhe prover com atalhos a geração do padrão de comentários acordado.
/* ==========================================================================
Bloco de comentário de seção
========================================================================== */
/* Bloco de comentário de sub-seção
========================================================================== */
/*
* Bloco de comentário de grupo
* Ideal para explicações em múltiplas linhas e documentação.
*/
/**
* Breve descrição usando o estilo de formato de comentário Doxygen
*
* A primeira frase da descrição longa começa aqui e continua
* nesta linha por um tempo finalmente concluindo aqui no final deste parágrafo.
*
* A descrição longa é ideal para explicações mais detalhadas e documentação.
* Ele pode incluir HTML de exemplo, URLs, ou qualquer outra informação
* que seja considerada necessária ou útil.
*
* @tag Esta é uma tag chamada 'tag'
*
* @todo Esta é uma declaração de tarefas que descreve uma tarefa atômica para ser
* concluída numa data posterior. Ela envolve depois de 80 caracteres e as linhas a
* seguir são Recuado por dois espaços.
*/
/* Comentário básico */
Para um CSS consistente é necessário ter sempre um espaçamento e indentação padronizada. Ajudando a tornar o código mais legível.
O formato de código escolhido deve garantir que o código seja: fácil de ler; fácil de comentar claramente; minimize a chance de introduzir erros acidentalmente; e resulte em úteis visualizações de diferença.
- Um seletor discreto por linha em um conjunto de regras com multi-seletores.
- Um único espaço antes da abertura das chaves em um conjunto de regras.
- Uma única declaração por linha em um bloco de declarativo.
- Um nível de indentação para cada declaração.
- Um único espaço depois dos dois pontos de uma declaração.
- Use valores minúsculos e abreviações hexadecimais, por exemplo, #aaa.
- Use aspas simples ou duplas de forma consistente. Preferência é por aspas duplas, por exemplo, conteúdo:" ".
- Citação valores de atributos em seletores, por exemplo, input [type="checkbox"].
- Onde for permitido, evitar especificar unidades para zero valores, por exemplo, margin: 0.
- Inclua um espaço após cada vírgula em propriedades separadas por vírgula ou valores de funções.
- Sempre inclua um ponto-e-vírgula no fim da última declaração em um bloco declarativo.
- Coloque o fechamento das chaves na mesma coluna que o primeiro caracter do conjunto de regras.
- Separe cada conjunto de regras por uma linha em branco.
Não recomendado:
.selector-1,.selector-2{
border:1px solid;
color:#333;
position:absolute;
}
.selector-3{
margin:0;
background-color:red;
}
Recomendado:
.selector-1,
.selector-2 {
border: 1px solid;
color: #333;
position: absolute;
}
.selector-3 {
margin: 0;
background-color: red;
}
Quando é necessário a declaração de apenas uma propriedade, podemos declarar de forma mais simples.
.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }
Organização de código é uma importante parte de qualquer base de código CSS, e crucial para grandes bases de código.
Separe logicamente partes distintas do código.
Use arquivos separados (concatenados por um processo de build) para ajudar a dividir o código para componentes distintos.
Para facilitar a legibilidade if
, else
, for
, while
, try
sempre tem espaços, chaves e ocorrem em múltiplas linhas. Também é importante cuidas os espaçamentos, fique atento a parênteses, chaves e quebras de linhas.
if ( condicao ) {
...
}
while ( condicao ) {
...
}
var i,
length = 100;
for ( i = 0; i < length; i++ ) {
...
}
var prop;
for ( prop in object ) {
...
}
if ( true ) {
...
} else {
...
}
Sempre declare as variáveis, declare variáveis globais utilizando window.
e variáveis locais com var
.
window.minhaVariavelGlobal = '';
var minhaVariavelLocal = '';
É uma boa prática quando necessário declarar mais de uma varivável aninhálas em uma única var. (quando possível)
var primeira,
segunda,
terceira;
Exemplo prático
window.foo = 'bar';
function strReplace() {
var name = 'José is',
prop = foo.replace('r', 'dass!');
return name + prop;
}
É recomendado para maior consistência na comparação utilizar ===
ou !==
.
if ( variavel === 1 ) {
...
}
if ( variavel !== '1' ) {
...
}
if ( variavel === 'Minha string' ) {
...
} else {
...
}
...
String:
if ( typeof variavel === 'string' ) {
}
Number:
if ( typeof variavel === 'number' ) {
}
Boolean:
if ( typeof variavel === 'boolean' ) {
}
Object:
if ( typeof variavel === 'object' ) {
}
Array:
if ( Array.isArray( variavel ) ) {
}
Null:
if ( variavel === null ) {
}
Null ou undefined:
if ( variavel == null ) {
}
Undefined variáveis Globais:
if ( typeof variavel === 'undefined' ) {
}
Undefined variáveis Locais:
if ( variavel === undefined ) {
}
Propriedades:
if ( object.prop === undefined ) {
}
if ( object.hasOwnProperty( prop ) ) {
}
if ( 'prop' in object ) {
}
funcoesNomeadasAssim;
variaveisNomeadasAssim;
ConstrutoresNomeadosAssim;
EnumNomeadosAssim;
metodosNomeadosAssim;
CONSTANTES_SIMBOLICAS_ASSIM;
'use strict';