---

layout: default

---

<div class="heading" id="toc">

<h2>Índice</h2>

<div class="section toc">

<div class="col">

<h4><a href="#html">HTML</a></h4>

<ul>

<li><a href="#html-syntax">Sintaxe</a></li>

<li><a href="#html-doctype">Doctype do HTML5</a></li>

<li><a href="#html-encoding">Encoding de caractéres</a></li>

<li><a href="#html-style-script">Inserindo CSS e JavaScript</a></li>

<li><a href="#html-practicality">Praticidade em vez de pureza</a></li>

<li><a href="#html-attribute-order">Ordem dos Atributos</a></li>

<li><a href="#html-boolean-attributes">Atributos booleanos</a></li>

<li><a href="#html-reducing-markup">Reduzindo o markup</a></li>

<li><a href="#html-javascript">Código gerado por JavaScript</a></li>

</ul>

</div>

<div class="col">

<h4><a href="#css">CSS</a></h4>

<ul>

<li><a href="#css-syntax">Sintaxe do CSS</a></li>

<li><a href="#css-declaration-order">Ordem das declarações</a></li>

<li><a href="#css-media-queries">Onde colocar as Media Queries</a></li>

<li><a href="#css-prefixed-properties">Propriedades com prefixo</a></li>

<li><a href="#css-single-declarations">Declarações únicas</a></li>

<li><a href="#css-shorthand">Propriedades resumidas</a></li>

<li><a href="#css-nesting">Aninhamento (nesting) no LESS e SASS</a></li>

<li><a href="#css-comments">Comentários</a></li>

<li><a href="#css-classes">Nomes de classes</a></li>

<li><a href="#css-selectors">Seletores</a></li>

<li><a href="#css-organization">Organização</a></li>

</ul>

</div>

<div class="section" id="golden-rule">

<div class="col">

<h2>Regra de ouro</h2>

<p>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 <a href="https://github.com/mdo/code-guide">abra uma Issue no Github</a>.</p>

</div>

<div class="col">

<blockquote>

<p>Toda linha de código deve parecer que foi escrita por uma única pessoa, não importa a quantidade de contribuidores.</p>

</blockquote>

</div>

<div class="heading" id="html">

<h2>HTML</h2>

<div class="section" id="html-syntax">

<div class="col">

<h3>Sintaxe do HTML</h3>

<ul>

<li>Use soft-tabs com dois espaços.</li>

<li>Elementos aninhados devem estar identados uma vez (2 espaços).</li>

<li>Sempre use aspas duplas, nunca aspas simples.</li>

<li>Nunca inclua uma barra invertida nos elementos viúvos (exemplo: <code>&lt;img&gt;</code> ou <code>&lt;hr&gt;</code>).</li>

</ul>

</div>

<div class="col">

{% highlight html %}{% include html/syntax.html %}{% endhighlight %}

</div>

<div class="section" id="html-doctype">

<div class="col">

<h3>Doctype do HTML5</h3>

<p>Reforce os padrões com este simples doctype no início de todas as páginas HTML.</p>

</div>

<div class="col">

{% highlight html %}{% include html/doctype.html %}{% endhighlight %}

</div>

<div class="section" id="html-encoding">

<div class="col">

<h3>Encoding de caractéres</h3>

<p>Assegure-se rapidamente que a renderizaçnao do seu conteúdo declarando o encoding de caractéres explicitamente.</p>

</div>

<div class="col">

{% highlight html %}{% include html/encoding.html %}{% endhighlight %}

</div>

<div class="section" id="html-style-script">

<div class="col">

<h3>Inserindo CSS e JavaScript</h3>

<p>De acordo com as especificações do HTML5, não há necessidade de especificar um atributo <code>type</code> quando incluímos arquivos de CSS e JavaScript como <code>text/css</code> e <code>text/javascript</code>.</p>

<h4>Links para especificação do HTML5</h4>

<ul>

<li><a href="http://www.w3.org/TR/2011/WD-html5-20110525/semantics.html#the-link-element">Usando link</a></li>

<li><a href="http://www.w3.org/TR/2011/WD-html5-20110525/semantics.html#the-style-element">Usando style</a></li>

<li><a href="http://www.w3.org/TR/2011/WD-html5-20110525/scripting-1.html#the-script-element">Usando scripts</a></li>

</ul>

</div>

<div class="col">

{% highlight html %}{% include html/style-script.html %}{% endhighlight %}

</div>

<div class="section" id="html-practicality">

<div class="col">

<h3>Praticidade em vez de pureza</h3>

<p>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.</p>

</div>

<div class="section" id="html-attribute-order">

<div class="col">

<h3>Ordem dos atributos</h3>

<p>Atributos HTML devem usar esta ordem em particular para facilitar a leitura do código.</p>

<ul>

<li><code>class</code></li>

<li><code>id</code></li>

<li><code>data-*</code></li>

<li><code>for</code>, <code>type</code>, ou <code>href</code></li>

<li><code>src</code>, <code>for</code>, <code>type</code>, <code>href</code></li>

<li><code>title</code>, <code>alt</code></li>

<li><code>aria-*</code>, <code>role</code></li>

</ul>

</div>

<div class="col">

{% highlight html %}{% include html/attribute-order.html %}{% endhighlight %}

</div>

<div class="section" id="html-boolean-attributes">

<div class="col">

<h3>Atributos booleanos</h3>

<p>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.</p>

<p>Para uma leitura adicional, consulte a <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#boolean-attributes">seção do WhatWG sobre atributos booleanos</a>:</p>

<blockquote>

<p>A presença de um atributo boleano representa um valor verdadeiro e a ausência do atributo representa um valor falso.</p>

</blockquote>

<p>Se você <em>precisa</em> incluir valores nos atributos, <strong>você não precisa</strong> seguir esta regra do WhatWG:</p>

<blockquote>

<p>Se o atributo está presente, seu valor deve ser uma string vazia ou [...] o nome canônico do atributo, sem espaços em branco.</p>

</blockquote>

<p>Resumindo, não adicione nenhum valor.</p>

</div>

<div class="col">

{% highlight html %}{% include html/boolean-attributes.html %}{% endhighlight %}

</div>

<div class="section" id="html-reducing-markup">

<div class="col">

<h3>Reduzindo o markup</h3>

<p>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:</p>

</div>

<div class="col">

{% highlight html %}{% include html/reducing-markup.html %}{% endhighlight %}

</div>

<div class="section" id="html-javascript">

<div class="col">

<h3>Markup gerado por Javascript</h3>

<p>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.</p>

</div>

<div class="heading" id="css">

<h2>CSS</h2>

<div class="section" id="css-syntax">

<div class="col">

<h3>Sintaxe do CSS</h3>

<ul>

<li>Use soft-tabs com dois espaços.</li>

<li>Quando agrupar seletores, deixe seletores individuais em uma linha.</li>

<li>Inclua um espaço antes de abrir um colchete.</li>

<li>Coloque o fechamento do colchete em uma nova linha.</li>

<li>Inclua um espaço depois dos dois pontos <code>:</code> em cada declaração de propriedade.</li>

<li>Cada declaração deve estar em sua própria linha para encontrarmos melhor os erros.</li>

<li>Feche todas as declarações com ponto-vírgula <code>;</code>.</li>

<li>Valores separados por vírgula devem incluir um espaço logo depois da vírgula (ex., <code>box-shadow</code>).</li>

<li>Não inclua espaços depois das vírgulas <em>como em</em> cores <<code>rgb()</code>, <code>rgba()</code>, <code>hsl()</code>, <code>hsla()</code> ou <code>rect()</code>. 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., <code>.5</code> em vez de <code>0.5</code>).</li>

<li>Deixe todos os valores hexadecimais em caixa baixa, exemplo: <code>#fff</code>. Letras com caixa baixa são mais fáceis de serem lidas e entendidas quando queremos scanear o documento.</li>

<li>Valores separados por vírgula devem incluir um espaço logo depois da vírgula.</li>

<li>Não inclua espaços depois das vírgulas <em>como em</em> cores <code>rgb()</code> ou <code>rgba()</code> e não inicie valores com zero.</li>

<li>Deixe todos os valores hexadecimais em caixa baixa, exemplo: <code>#fff</code>.</li>

<li>Use cores em hexadecimal abrevidas quando puder, exemplo: <code>#fff</code> em vez de <code>#ffffff</code>.</li>

<li>Coloque aspas nos valores em seletores com atributos, exemplo: <code>input[type="text"]</code>.</li>

<li>Evite especificar unidades quando os valores forem 0, exemplo: <code>margin: 0;</code> em vez de <code>margin: 0px;</code>.</li>

</ul>

<p>Dúvidas sobre os termos usados aqui? Veja a <a href="http://en.wikipedia.org/wiki/Cascading_Style_Sheets#Syntax">seção de sintaxe dos CSS</a> na Wikipedia.</p>

</div>

<div class="col">

{% highlight css %}{% include css/syntax.css %}{% endhighlight %}

</div>

<div class="section" id="css-declaration-order">

<div class="col">

<h3>Ordem das declarações</h3>

<p>Declarações relacionadas devem ser agrupadas segundo a seguinte ordem:</p>

<ol>

<li>Posicionamento</li>

<li>Box model</li>

<li>Tipografia</li>

<li>Visual</li>

</ol>

<p>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.</p>

<p>Tudo o mais que toma lugar <em>dentro</em> do componente ou não impacta as duas seções anteriores, vem por último.</p>

<p>Para uma lista completa de propridades e suas ordens, por favor veja <a href="http://twitter.github.com/recess">Recess</a>,</p>

<p>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.</p>

<p>Para uma lista completa das propriedades e suas ordens, por favor verifique a página do <a href="http://twitter.github.com/recess">Recess</a>.</p>

</div>

<div class="col">

{% highlight css %}{% include css/declaration-order.css %}{% endhighlight %}

</div>

<div class="section" id="css-media-queries">

<div class="col">

<h3>Onde colocar as Media Queries</h3>

<p>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:</p>

</div>

<div class="col">

{% highlight css %}{% include css/media-queries.css %}{% endhighlight %}

</div>

<div class="section" id="css-prefixed-properties">

<div class="col">

<h3>Propriedades com prefixo</h3>

<p>Quando usar prefixos de browsers, idente cada propriedade alinhada verticalmente para facilitar a edição multi-linha.</p>

<p>No Textmate, use <strong>Text &rarr; Edit Each Line in Selection</strong> (&#8963;&#8984;A). No Sublime Text 2, use <strong>Selection &rarr; Add Previous Line</strong> (&#8963;&#8679;&uarr;) e <strong>Selection &rarr; Add Next Line</strong> (&#8963;&#8679;&darr;).</p>

</div>

<div class="col">

{% highlight css %}{% include css/prefixed-properties.css %}{% endhighlight %}

</div>

<div class="section" id="css-single-declarations">

<div class="col">

<h3>Declarações únicas</h3>

<p>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:</p>

</div>

<div class="col">

{% highlight css %}{% include css/single-declarations.css %}{% endhighlight %}

</div>

<div class="section" id="css-shorthand">

<div class="col">

<h3>Propriedades resumidas</h3>

<p>Esforce-se muito para usar declarações de propriedades resumidas onde você define todos os valores dessa propriedade. As propriedades resumidas mais usadas incluem:</p>

<ul>

<li><code>padding</code></li>

<li><code>margin</code></li>

<li><code>font</code></li>

<li><code>background</code></li>

<li><code>border</code></li>

<li><code>border-radius</code></li>

</ul>

<p>Frequentemente 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.</p>

<p>O Mozilla Developer Network tem um ótimo artigo em <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties">shorthand properties</a> para quem não está familiarizado essa forma de escrever.</p>

</div>

<div class="col">

{% highlight css %}{% include css/shorthand.css %}{% endhighlight %}

</div>

<div class="section" id="css-nesting">

<div class="col">

<h3>Aninhamento (nesting) no LESS e SASS</h3>

<p>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.</p>

</div>

<div class="col">

{% highlight scss %}{% include css/nesting.scss %}{% endhighlight %}

</div>

<div class="heading" id="css-human-readable">

<h2>Legível para humanos</h2>

<div class="section" id="css-comments">

<div class="col">

<h3>Comentários</h3>

<p>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.</p>

<p>Certifique-se de escrever em sentenças completas ou grandes comentários e frases sucintas para notas gerais.</p>

<div class="col">

{% highlight css %}{% include css/comments.css %}{% endhighlight %}

</div>

<div class="section" id="css-class-names">

<div class="col">

<h3>Nomes de classes</h3>

<ul>

<li>Mantenha as classes em caixa baixa e use traços (não use underscores ou camelCase).</li>

<li>Evite usar arbitrariamente notações abreviadas.</li>

<li>Mantenha-as pequenas e sucintas ao máximo possível.</li>

<li>Use nomes com significado; use nomes ligados à estrutura em vez do visual.</li>

<li>Prefixe nomes de classes baseadas nos componentes pais mais próximos.</li>

</ul>

</div>

<div class="col">

{% highlight css %}{% include css/class-names.css %}{% endhighlight %}

</div>

<div class="section" id="css-selectors">

<div class="col">

<h3>Seletores</h3>

<ul>

<li>Use classes em vez de nomes de tags.</li>

<li>Mantenha os seletores pequenos e limite o número de elementos em no máximo três.</li>

<li>Use nomes de classes do elemento pais <strong>somente</strong> quando necessário (ex: quando não usar classes prefixadas).</li>

</ul>

<p>Leitura adicional:</p>

<ul>

<li><a href="http://markdotto.com/2012/02/16/scope-css-classes-with-prefixes/">Scope CSS classes with prefixes</a></li>

<li><a href="http://markdotto.com/2012/03/02/stop-the-cascade/">Stop the cascade</a></li>

</ul>

</div>

<div class="col">

{% highlight css %}{% include css/selectors.css %}{% endhighlight %}

</div>

<div class="section" id="css-organization">

<div class="col">

<h3>Organização</h3>

<ul>

<li>Organize seções do código por componentes.</li>

<li>Desenvolva uma hierarquia de comentários consistente.</li>

<li>Se usar múltiplos arquivos CSS, quebre-os em componentes.</li>

</ul>

</div>

<div class="section" id="css-editor-prefs">

<div class="col">

<h3>Preferências de editor</h3>

<p>Defina seu editor com as seguintes configurações para evitar inconsistências comuns no código e diffs sujos:</p>

<ul>

<li>Use soft-tabs com 2 espaços</li>

<li>Apague os espaços em brancos ao salvar</li>

<li>Defina o encoding como UTF-8</li>

<li>Coloque uma nova linha no final dos arquivos</li>

</ul>

<p>Considere documentar e aplicar estas configurações para o seu projeto com o <code>.editorconfig</code>. Para um exemplo, veja <a href="https://github.com/twbs/bootstrap/blob/master/.editorconfig">o arquivo utilizado no Bootstrap</a>. Aprenda mais em <a href="http://editorconfig.org">EditorConfig</a></p>

</div>