Guia de Estilo de Código

"Toda linha de código deve parecer que foi escrita por uma única pessoa, não importa a quantidade de contribuidores." - Provérbio Chinês

O documento a seguir descreve as regras de escrita nas linguagens de desenvolvimento que utilizamos: HTML, CSS e JavaScript.

A ideia desse documento/repositório não é ser um guia de código completo. Mas, sim, ter um local para que os times que participam dos projetos possam se informar sobre padrões de códigos atualmente usados.

Como este documento é novo, algumas regras podem não ter sido aplicadas em projetos antigos.

Este é um documento vivo e mudanças podem, e devem, se necessário, acontecer a qualquer momento.

Sumário

1. Commits

Para facilitar a contribuição de qualquer pessoa nos projetos, todas as mensagens de commit, pull requests ou discussões devem ser em Inglês.

Antes de commitar ajustes no projeto, verifique se já existe uma task/issue aberta e faça referência a ela usando '#' no início da sua mensagem de commit.

// Bom
git commit -m "#798 Add placeholder on input"

// Ruim
git commit -m "Add placeholder on input"

2. HTML

A principal influencia das regras de HTML é o Code Guide by @mdo.

HTML Sumário

2.1. HTML Sintaxe

Use soft-tabs com dois espaços. Quatro espaços, dependendo do tamanho das linhas/código, pode dificultar uma rápida leitura.

Você pode configurar o seu editor preferido dessa forma.

<!-- Bom -->
<nav class="navbar">
  <ul class="nav">
    <li class="nav-item">
      <a class="nav-link">

<!-- Ruim-->
<nav class="navbar">
      <ul class="nav">
            <li class="nav-item">
                  <a class="nav-link">

Sempre use aspas duplas.

<!-- Bom -->
<main class="main">

<!-- Ruim -->
<main class='main'>

Não inclua / em elementos viúvos.

<!-- Bom -->
<hr>

<!-- Ruim -->
<hr />

Separe os blocos usando uma linha vazia e agrupe os elementos internos do bloco.

<!-- Bom -->
<ul class="nav-tabs">
  <li>...</li>
  <li>...</li>
  <li>...</li>
  <li>...</li>
</ul>

<div class="tab-content">
  ...
</div>

<!-- Ruim -->
<ul class="nav-tabs">

  <li>...</li>

  <li>...</li>

  <li>...</li>

  <li>...</li>

</ul>
<div class="tab-content">
  ...
</div>

2.2. HTML Comentários

Siga esta regra para adicionar comentários no HTML.

<!-- este é um bom exemplo INICIO-->
<!-- este é um bom exemplo FIM -->

2.3. HTML Encoding de Caracteres

Sempre use UTF-8 para encoding de caracteres.

<head>
  <meta charset="UTF-8">
</head>

2.4. HTML Ordem dos Atributos

Os atributos do HTML devem estar na seguinte ordem para facilitar a leitura.

class
id, name
data-*
src, for, type, href
title, alt
aria-*, role

<a class="..." id="..." data-modal="toggle" href="#">

<input class="form-control" type="text">

<img class="img-rounded" src="..." alt="...">

2.5. HTML Performance

Nos includes dos arquivos CSS e JavaScript não é necessário especificar o tipo de arquivo como text/css e text/javascript.

<!-- Bom -->
<link rel="stylesheet" href="assets/css/style.css">
<script src="scripts.min.js"></script>

<!-- Ruim -->
<script src="scripts.min.js" type="text/javascript"></script>
</head>
<body>

Para uma melhor performance, todos os arquivos JavaScripts devem estar antes de fechar o <body>, no fim do documento.

<!-- Bom -->
<script src="scripts.min.js"></script>
</body>

<!-- Ruim -->
<script src="scripts.min.js"></script>
</head>
<body>

Quando o projeto usar apenas HTML, sempre minifique o código. Automatizadores de tarefas como o Gulp tornam isso muito mais fácil.

<!-- Bom -->
<html><head>...</head><body><div class="container">...</div></body></html>

<!-- Ruim -->
<html>
  <head>
    ...
  </head>
  <body>
    <div class="container">
      ...
    </div>
  </body>
</html>

2.6. HTML Código Base

O código a seguir é uma base em HTML para iniciar rapidamente os projetos.

<!DOCTYPE html>
<html lang="pt-br">
<head>

<meta charset="utf-8">
<meta name="format-detection" content="telephone=no">
<meta name="viewport" content="width=device-width">

<link rel="shortcut icon" href="assets/img/ico/favicon.ico">
<link rel="logo" type="image/svg" href="assets/img/logo/logo.svg">
<link rel="stylesheet" href="assets/css/style.css">

<title></title>

</head>
<body>

<!-- Scripts -->
<script src="js/scripts.min.js"></script>

</body>
</html>

Para fornecer suporte para versões antigas do Internet Explorer...

<!DOCTYPE html>
<!--[if IE]><![endif]-->
<!--[if IE 7 ]><html lang="en" class="ie7"><![endif]-->
<!--[if IE 8 ]><html lang="en" class="ie8"><![endif]-->
<!--[if IE 9 ]><html lang="en" class="ie9"><![endif]-->
<!--[if (gt IE 9)|!(IE)]><!--><html lang="pt-br"><!--<![endif]-->
<head>
...

2.7. HTML Reduzindo o Markup

Sempre que possível, evite elementos pais supérfluos quando escrever HTML.

<!-- Bom -->
<img class="avatar" src="...">

<!-- Ruim -->
<span class="avatar">
  <img src="...">
</span>

3. CSS

A principal influência para as regras de CSS são o Code Guide by @mdo e o idiomatic CSS.

CSS Sumário

3.1. CSS Sintaxe

Use soft-tabs com dois espaços.

Você pode configurar o seu editor preferido dessa forma.

/* Bom */
.nav-item {
  display: inline-block;
  margin: 0 5px;
}

/* Ruim */
.nav-item {
    display: inline-block;
    margin: 0 5px;
}

Sempre use aspas duplas.

/* Bom */
[type="text"]
[class^="..."]

.nav-item:after {
  content: "";
}

/* Ruim */
[type='text']
[class^='...']

.nav-item:after {
  content: '';
}

Inclua um espaço antes de abrir o { da regra.

/* Bom */
.header {
  ...
}

/* Ruim */
.header{
  ...
}

Inclua um espaço depois do : da declaração.

/* Bom */
.header {
  margin-bottom: 20px;
}

/* Ruim */
.header{
  margin-bottom:20px;
}

Inclua um ; no fim da declaração.

/* Bom */
.header {
  margin-bottom: 20px;
}

/* Ruim */
.header{
  margin-bottom:20px
}

Quando agrupar seletores, mantenha apenas um seletor por linha.

/* Bom */
.selector-1,
.selector-2,
.selector-3 {
  ...
}

/* Ruim */
.selector-1, .selector-2, .selector-3 {
  ...
}

Declarações únicas devem ficar em uma linha apenas.

/* Bom */
.selector-1 { width: 50%; }

/* Ruim */
.selector-1 {
  width: 50%;
}

Separe as regras por uma linha em branco, inclusive regras de linha única.

/* Bom */
.selector-1 {
  ...
}

.selector-2 {
  ...
}

/* Ruim */
.selector-1 {
  ...
}
.selector-2 {
  ...
}

Use texto em caixa baixa, valores hexadecimais reduzidos e não especifique unidades quando o valor é zero.

/* Bom */
.selector-1 {
  color: #aaa;
  margin: 0;
}

/* Ruim */
.selector-1 {
  color: #AAAAAA;
  margin: 0px;
}

3.2. CSS Ordem de Declaração

As declarações devem ser adicionadas em contexto.

/* Bom */
.selector-1 {
  /* box model */
  display: block;
  height: 200px;
  margin: 5px;
  padding: 5px;
  width: 200px;
  
  /* positioning */
  float: left;
  
  /* Typography */
  font-family: Arial;
  font-style: italic;
  font-weight: bold;
  
  /* visual */
  background: #fff;
  border: #333 solid 1px;
  color: #333;
}

/* Ruim */
.selector-1 {
  padding: 5px;
  height: 200px;
  background: #fff;
  margin: 5px;
  width: 200px;
  color: #333;
  border: #333 solid 1px;
  display: block;
  font-family: Arial;
  font-style: italic;
  font-weight: bold;
  float: left;
}

3.3. CSS Nome das Classes

Mantenha as classes em caixa baixa e use hífen para separar os nomes.

/* Bom */
.nav-item { ... }

/* Ruim */
.NavItem { ... }
.nav_item { ... }

Hífens servem como uma transição natural entre classes relacionadas. O primeiro nome deve ser baseado no pai imediato da classe que deseja criar.

/* Bom */
.navbar { ... }
.nav { ... }
.nav-item { ... }
.nav-link { ... }

/* Ruim */
.item-nav { ... }
.link-nav { ... }

Nunca use abreviações nos nomes das classes.

Sempre use nomes de classe semanticamente relacionados com o conteúdo do elemento e jamais relacionados com a formatação visual deste.

/* Bom */
.btn { ... }
.page-header { ... }
.progress-bar { ... }
.secundary-box { ... }

/* Ruim */
.s { ... }
.ph { ... }
.block { ... }
.blue-box { ... }

3.4. CSS Performance

Evite o uso de IDs. Use somente quando necessário de fato.

/* Bom */
.header { ... }
.section { ... }

/* Ruim */
#header { ... }
#section { ... }

Evite seletores padrões para regras genéricas. Sempre use classes.

/* Bom */
.form-control { ... }
.header { ... }
.section { ... }

/* Ruim */
input[type="text"] { ... }
header
section

Evite elementos aninhados. A preferência é sempre para o uso de classes.

/* Bom */
.navbar { ... }
.nav { ... }
.nav-item { ... }
.nav-link { ... }

/* Ruim */
.navbar ul { ... }
.navbar ul li { ... }
.navbar ul li a { ... }

Aninhe somente quando precisar alterar o comportamento de uma classe por interferência de outra. Mantenha um limite de três elementos aninhados.

/* Bom */
.modal-footer .btn { ... }
.progress.active .progress-bar { ... }

/* Ruim */
.modal-btn { ... }
.progress.active .progress-bar .progress-item span { ... }

Sempre minifique o código CSS. Automatizadores de tarefas como o Gulp tornam isso muito mais fácil.

<!-- Bom -->
.navbar { ... }.nav { ... }.nav-item { ... }.nav-link { ... }

<!-- Ruim -->
.nav-item {
  ...
}
.nav-link {
  ...
}

3.5 Mobile First and Media Queries

Comece o desenvolvimento usando regras genéricas e adicione media queries começando com mobile.

Compartilho um artigo com mais informações CSS Modular com Mobile First.

/* Bom */
.navbar {
  margin-bottom: 20px;
}

@media (min-width: 480px) {
  .navbar {
    padding: 10px;
  }
}

@media (min-width: 768px) {
  .navbar {
    position: absolute;
    top: 0;
    left: 0;
  }
}

@media (min-width: 992px) {
  .navbar {
    position: fixed;
  }
}

/* Ruim */
.navbar {
  position: fixed;
  top: 0;
  left: 0;
}

@media (max-width: 767px) {
  .navbar {
    position: static;
    padding: 10px;
  }
}

Mantenha os media queries o mais próximo possível da regra que deseja alterar. Jamais coloque em documentos separados ou no fim do stylesheet.

.navbar { ... }
.nav { ... }
.nav-item { ... }

@media (min-width: 480px) {
  .navbar { ... }
  .nav { ... }
  .nav-item { ... }
}

3.6. CSS Comentários

Todos os comentários devem ser feitos usando a sintaxe do pré-processador em uso.

//
// Seção
// ==================================================

//
// Sub-seção
// --------------------------------------------------

// Separador 
// --------------------------------------------------

//
// Bloco de comentário
//
//

// Comentário simples

4. CSS Pré-processadores

O ideal é utlizar pré-processadores em todos os projetos. Atualmente a equipe utiliza Sass, mas nada impede que a equipe adote outro pré-processador.

CSS Pré-processadores Sumário

4.1. CSS Pré-processadores Sintaxe

Use soft-tabs com dois espaços. Você pode configurar o seu editor preferido dessa forma.

// Bom
.nav-item {
  display: inline-block;
}

// Ruim
.nav-item {
    display: inline-block;
}

Nunca esqueça do ponto e vírgula, dois pontos e chaves.

// Bom
.header {
  position: fixed;
  top: 0;
  right: 0;
  left: 0;
}

// Ruim
.header 
  position: fixed
  top: 0
  right: 0
  left: 0

Quando agrupar seletores, mantenha apenas um seletor por linha.

// Bom
.selector-1,
.selector-2,
.selector-3 
  ...
 

// Ruim
.selector-1, .selector-2, .selector-3 
  ...

Separe as regras dos elementos aninhados por uma linha vazia e outros blocos de regras com duas linhas vazias.

// Bom
.navbar {
  margin: 0 0 20px;

  li {
    display: inline-block;
  }
}

.nav {
  display: block;

  li {
    float: left;
  }
}

// Ruim
.navbar {
  margin: 0 0 20px; 
  li {
    display: inline-block;
  } 
}
.nav {
  display: block; 
  li {
    float: left;
  }
}

Use $ para as váriaveis e @ para mixins.

// Bom
$gray-darker  = #111
$gray-dark    = #393C45
$gray         = #555
$gray-light   = #aaa
$gray-lighter = #ECF1F5
$gray-white   = #fbfbfb


@list-unstyled {
  color: $gray;
  margin-bottom: 0;
  padding-left: 0;
  list-style: none;  
}

.list-item {
  @include list-unstyled;
}

4.2. CSS Pré-processadores Performance

Cuidado com a facilidade de aninhar elementos com os pré-processadores. Continue evitando aninhamentos.

Se utilizar, mantenha um limite de três elementos aninhados.

// Bom
.nav-item {
  ...
}

// Ruim
.navbar {
  .nav {
    .nav-item {
      ... 
    }
  }
}

Crie mixins e use o @include para adicionar em vários elementos.

@mixin clearfix {
  &:before,
  &:after {
    content: " "; 
    display: table; 
  }

  &:after {
    clear: both; 
  }
}

.header {
  @include clearfix; 
}

.footer {
  @include: clearfix; 
}

4.3. CSS Pré-processadores Media Queries

Forneça as regras de media queries dentro do elemento.

.navbar {
  position: absolute;
  top: 5px;
  z-index: 5;
   
  @media (min-width: $screen-sm) {
    position: fixed;
    margin-right: $space-sm;
  }

  @media (min-width: $screen-md) { 
    right: 0; 
    top: 10px; 
  }
}

4.4. CSS Pré-processadores Comentários

Forneça um sumário no cabeçalho dos arquivos.

//  
// Variables
//
// 1. Colors
// 2. Spaces 
// 3. Grid 
// 4. Typography
//
// ===============================================================

// 
// 1. Colors
// --------------------------------------------------

...

// 
// 2. Spaces
// --------------------------------------------------

...

Para elementos principais.

// 
// 1. Header
// -------------------------------------------------- 
...

Para os elementos filhos.

// 1.1 Header Item
// -------------------------------------------------- 
...

Para comentários genéricos.

// Comentário simples

// Bloco de
// Comentário
...

5. JavaScript

As principais influencias para as regras de escrita em JavaScript são o idiomatic.js e o Zeno Rocha Coding Style.

JavaScript Sumário

5.1. JavaScript Sintaxe

Use soft-tabs com dois espaços. Você pode configurar o seu editor preferido dessa forma.

// Bom
while (condition) {
  statements
}

// Ruim
while (condition) {
    statements
}

Sempre use ;.

// Bom
var me = $(this);
test();

// Ruim
var me = $(this)
test()

Sempre use aspas simples.

// Bom
var string = '<p class="foo">Lorem Ipsum</p>';
var noteClick = me.attr('data-note');

// Ruim
var string = "<p class="foo">Lorem Ipsum</p>";
var noteClick = me.attr("data-note");

Mantenha o else na mesma linha em que fechar o if.

// Bom
if ( true ) {
  ...
} else {
  ...
}

// Ruim
if ( true ) {
  ...
}
else {
  ...
}

Adicione espaços entre os operadores.

// Bom
for (i = 0; i < 10; i++) {
  ...
}

// Ruim
for (i=0;i<10;i++) {
  ...
}

Nunca adicione espaço entre a chave de função e o nome da função.

// Bom
foo(function() {
  ...
});

// Ruim
foo ( function () {
  ...
});

Adicione espaços fora dos (), mas nunca dentro deles.

// Bom
if (condition) {
  statement
}

// Ruim
if( condition ){
  statement
}

Para condicionais, sempre use {}.

// Bom
if (condition) {
  statement
} else if (condition) {
  statement
} else {
  statement
}

// Ruim
if (condition) statement;
else if (condition) statement;
else statement;

Para checar igualdade, use === ao invés de usar ==.

// Bom
if (foo === 'foo') {
  statement
}

// Ruim
if (foo == 'foo') {
  statement
}

5.2. JavaScript Variáveis

Todas as variáveis devem ser declaradas antes do seu uso.

// Bom
var me = $(this);
var noteClick = me.attr('data-note');
notes[noteClick].play();

// Ruim
notes[noteClick].play();
var me = $(this);
var noteClick = me.attr('data-note');

Sempre use var para declarar uma variável.

// Bom
var me = $(this);

// Ruim
me = $(this);

5.3. JavaScript Performance

Use o JSHint para detectar erros e potenciais problemas.

Sempre concatene e minifique o código JavaScript. Automatizadores de tarefas como o Gulp tornam isso muito mais fácil.

5.4. JavaScript and HTML5 Data Attributes

Evite usar classes para iniciar interações em JavaScript. Prefira usar HTML5 Data Attributes.

// Bom
$('[data-toggle="tab"]');

// Ruim
$('.tab');

Essa abordagem mantém as classes responsáveis apenas pela estilização.

Dessa forma, elementos que compartilhar o mesmo estilo, mas não possuem as mesmas interações, podem funcionar separadamente.

5.5. JavaScript Comentários

Uma única linha acima do código que é comentado.

// Bom
// Bom exemplo de comentário
var me = $(this);

// Ruim
var me = $(this); // Exemplo ruim de comentário

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Guia de Estilo de Código

Sumário

1. Commits

2. HTML

HTML Sumário

2.1. HTML Sintaxe

2.2. HTML Comentários

2.3. HTML Encoding de Caracteres

2.4. HTML Ordem dos Atributos

2.5. HTML Performance

2.6. HTML Código Base

2.7. HTML Reduzindo o Markup

3. CSS

CSS Sumário

3.1. CSS Sintaxe

3.2. CSS Ordem de Declaração

3.3. CSS Nome das Classes

3.4. CSS Performance

3.5 Mobile First and Media Queries

3.6. CSS Comentários

4. CSS Pré-processadores

CSS Pré-processadores Sumário

4.1. CSS Pré-processadores Sintaxe

4.2. CSS Pré-processadores Performance

4.3. CSS Pré-processadores Media Queries

4.4. CSS Pré-processadores Comentários

5. JavaScript

JavaScript Sumário

5.1. JavaScript Sintaxe

5.2. JavaScript Variáveis

5.3. JavaScript Performance

5.4. JavaScript and HTML5 Data Attributes

5.5. JavaScript Comentários

6. Referências

7. Licença

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Packages