Reforce isso, concordando com estas guidelines todas as vezes. Pequenos ou grandes, mostre o que está incorreto. Para adições ou contribuições para este Guia de Código, por favor abra uma Issue no Github.
Toda linha de código deve parecer que foi escrita por uma única pessoa, não importa a quantidade de contribuidores.
<img> ou <hr>).<!DOCTYPE html>
<html>
<head>
<title>Page title</title>
</head>
<body>
<img src="images/company-logo.png" alt="Company">
<h1 class="hello-world">Hello, world!</h1>
</body>
</html>Reforce os padrões com este simples doctype no início de todas as páginas HTML.
<!DOCTYPE html>
<html>
<head>
</head>
</html>Assegure-se rapidamente a renderização do seu conteúdo declarando o encoding de caractéres explicitamente.
<head>
<meta charset="UTF-8">
</head>De acordo com as especificações do HTML5, não há necessidade de especificar um atributo type quando incluímos arquivos de CSS e JavaScript como text/css e text/javascript.
<!-- External CSS -->
<link rel="stylesheet" href="code-guide.css">
<!-- In-document CSS -->
<style>
/* ... */
</style>
<!-- JavaScript -->
<script src="code-guide.js"></script>Esforce-se para manter o padrão e a semântica do HTML, mas não às custas da praticidade. Use o mínimo de código com a menor complexidade possível.
Atributos HTML devem usar esta ordem em particular para facilitar a leitura do código.
classiddata-*for, type, ou hrefsrc, for, type, hreftitle, altaria-*, role<a class="..." id="..." data-modal="toggle" href="#">
Example link
</a>
<input class="form-control" type="text">
<img src="..." alt="...">Um atributo boleano é o único que não precisa ter valores declarados. O XHTML precisa que você declare um valor, mas no HTML5 isso não é necessário.
Para uma leitura adicional, consulte a seção do WhatWG sobre atributos booleanos:
A presença de um atributo boleano representa um valor verdadeiro e a ausência do atributo representa um valor falso.
Se você precisa incluir valores nos atributos, você não precisa seguir esta regra do WhatWG:
Se o atributo está presente, seu valor deve ser uma string vazia ou [...] o nome canônico do atributo, sem espaços em branco.
Resumindo, não adicione nenhum valor.
<input type="text" disabled>
<input type="checkbox" value="1" checked>
<select>
<option value="1" selected>1</option>
</select>Sempre que possível, evite elementos pais supérfluos quando escrever HTML. Muitas vezes é necessário uma interação ou refatoração, mas isso produz pouco HTML. Veja o seguinte exemplo:
<!-- Not so great -->
<span class="avatar">
<img src="...">
</span>
<!-- Better -->
<img class="avatar" src="...">Escrever código em um arquivos Javascript faz com que o conteúdo seja difícil de ser encontrado, difícil de ser editado e o torna menos performático. Evite fazer isso o máximo possível.
: em cada declaração de propriedade.;.box-shadow).rgb(), rgba(), hsl(), hsla() ou rect(). Isto ajuda a diferenciar múltiplos valores (vírgulas, sem espaço) de cores de propriedades múltiplas (vírgulas, com espaço). Também não coloque valores iniciados com zero (ex., .5 em vez de 0.5).#fff. Letras com caixa baixa são mais fáceis de serem lidas e entendidas quando queremos scanear o documento.rgb() ou rgba() e não inicie valores com zero.#fff.#fff em vez de #ffffff.input[type="text"].margin: 0; em vez de margin: 0px;.Dúvidas sobre os termos usados aqui? Veja a seção de sintaxe dos CSS na Wikipedia.
/* Bad CSS */
.selector, .selector-secondary, .selector[type=text] {
padding:15px;
margin:0px 0px 15px;
background-color:rgba(0, 0, 0, 0.5);
box-shadow:0 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}
/* Good CSS */
.selector,
.selector-secondary,
.selector[type="text"] {
padding: 15px;
margin: 0 0 15px;
background-color: rgba(0,0,0,.5);
box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}Declarações relacionadas devem ser agrupadas segundo a seguinte ordem:
Posicionamento vem primeiro por que isto pode remover um elemento do fluxo normal do documento e substituir estilos relacionados. O box model vem depois pois ele dita as dimensões e lugar do componente.
Tudo o mais que toma lugar dentro do componente ou não impacta as duas seções anteriores, vem por último.
Para uma lista completa de propridades e suas ordens, por favor veja Recess,
Declarações relacionadas devem ser agrupadas, colocando posicionamento e as propriedades de box-model perto do topo, seguido das propriedades de tipografia e depois propriedades visuais.
Para uma lista completa das propriedades e suas ordens, por favor verifique a página do Recess.
.declaration-order {
/* Positioning */
position: absolute;
top: 0;
right: 0;
bottom: 0;
left: 0;
z-index: 100;
/* Box-model */
display: block;
float: right;
width: 100px;
height: 100px;
/* Typography */
font: normal 13px "Helvetica Neue", sans-serif;
line-height: 1.5;
color: #333;
text-align: center;
/* Visual */
background-color: #f5f5f5;
border: 1px solid #e5e5e5;
border-radius: 3px;
/* Misc */
opacity: 1;
}Coloque as Media Queries o mais perto possível de suas regras originais. Não as coloque separadas em outros arquivos ou no final do documento. Se você fizer isso, outros poderão não encontrá-las no futuro. Veja um exemplo típico:
.element { ... }
.element-avatar { ... }
.element-selected { ... }
@media (min-width: 480px) {
.element { ...}
.element-avatar { ... }
.element-selected { ... }
}Quando usar prefixos de browsers, idente cada propriedade alinhada verticalmente para facilitar a edição multi-linha.
No Textmate, use Text → Edit Each Line in Selection (⌃⌘A). No Sublime Text 2, use Selection → Add Previous Line (⌃⇧↑) e Selection → Add Next Line (⌃⇧↓).
/* Prefixed properties */
.selector {
-webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
box-shadow: 0 1px 2px rgba(0,0,0,.15);
}Em lugares onde são definidas apenas uma linha de propriedade, considere remover as quebras de linha para melhorar a leitura e edição. Considere este exemplo:
/* Single declarations on one line */
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }
/* Multiple declarations, one per line */
.sprite {
display: inline-block;
width: 16px;
height: 15px;
background-image: url(../img/sprite.png);
}
.icon { background-position: 0 0; }
.icon-home { background-position: 0 -20px; }
.icon-account { background-position: 0 -40px; }Esforce-se muito para usar declarações de propriedades resumidas onde você define todos os valores dessa propriedade. As propriedades resumidas mais usadas incluem:
paddingmarginfontbackgroundborderborder-radiusFrequentemente não precisamos definir todos os valores que uma propriedade representa. Por exemplo, os títulos do HTML tem margens no top e bottom definidas por padrão, então, quando necessário, apenas substitua estes dois valores. O uso excessivo de propriedades resumidas (ou shorthand properties) pode fazer com que o código fique um pouco bagunçado quando substituímos propriedades não utilizadas.
O Mozilla Developer Network tem um ótimo artigo em shorthand properties para quem não está familiarizado essa forma de escrever.
/* Bad example */
.element {
margin: 0 0 10px;
background: red;
background: url("image.jpg");
border-radius: 3px 3px 0 0;
}
/* Good example */
.element {
margin-bottom: 10px;
background-color: red;
background-image: url("image.jpg");
border-top-left-radius: 3px;
border-top-right-radius: 3px;
}Evite aninhar seletores (fazer "nesting"). Só porque você pode fazer isso, não significa que você deve fazê-lo sempre. Considere aninhar se você tem um escopo de estilos para um pai e se há múltiplos elementos para serem aninhados.
// Without nesting
.table > thead > tr > th { ... }
.table > thead > tr > td { ... }
// With nesting
.table > thead > tr {
> th { ... }
> td { ... }
}Código é escrito e mantido por pessoas. Certifique-se de que o código é descritivo, bem comentado e amigável para os outros. Grandes pedaços de comentários devem ter contexto e não devem apenas reiterar um nome de classe ou componente.
Certifique-se de escrever em sentenças completas ou grandes comentários e frases sucintas para notas gerais.
/* Bad example */
/* Modal header */
.modal-header {
...
}
/* Good example */
/* Wrapping element for .modal-title and .modal-close */
.modal-header {
...
}/* Bad example */
.t { ... }
.red { ... }
.header { ... }
/* Good example */
.tweet { ... }
.important { ... }
.tweet-header { ... }Leitura adicional:
/* Bad example */
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }
/* Good example */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }Defina seu editor com as seguintes configurações para evitar inconsistências comuns no código e diffs sujos:
Considere documentar e aplicar estas configurações para o seu projeto com o .editorconfig. Para um exemplo, veja o arquivo utilizado no Bootstrap. Aprenda mais em EditorConfig