Skip to content

Latest commit

 

History

History

pt-BR

Folders and files

NameName
Last commit message
Last commit date

parent directory

..

README.md

README.md

 
 

README.md

Meu Estilo de Código

license GitHub contributors

"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 utilizo: HTML, CSS e JavaScript.

A ideia desse repositório não é ser um guia de código completo. Mas sim ter um local para que eu e outros desenvolvedores que participam dos meus projetos conseguirem se informar dos padrões de códigos usados.

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

Este é um documento vivo e mudanças podem acontecer a qualquer momento.

Sumário

  1. Commits
  2. HTML
  3. Pug
  4. CSS
  5. CSS Pré-processadores
  6. JavaScript
  7. Boilerplate
  8. Referências
  9. Traduções

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 existe uma issue aberta e faça referência a ela usando '#' na sua mensagem de commit.

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

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

  1. HTML Sintaxe
  2. HTML Comentários
  3. HTML Encoding de Caracteres
  4. HTML Ordem dos Atributos
  5. HTML Performance
  6. HTML Código Base

2.1. HTML Sintaxe

Use soft-tabs com dois espaços. Você pode configurar o seu editor 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 -->
<!-- /Fechando um bom exemplo -->

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.

  1. class
  2. id, name
  3. data-*
  4. src, for, type, href
  5. title, alt
  6. aria-*, role
<a class="..." id="..." data-modal="#overlay" 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 type="text/JavaScript" src="scripts.min.js"></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 Grunt 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 rápidamente 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, initial-scale=1.0, user-scalable=no">
  <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> 
</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>
...

3. Pug

Atualmente usando Pug como template engine.

Pug Sumário

  1. Pug Sintaxe
  2. Pug Comentários
  3. Pug Código Base

3.1. Pug Syntax

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

//- Bom
nav.navbar
  ul.nav
    li.nav-item
      a.nav-link

//- Ruim
nav.navbar
    ul.nav
        li.nav-item
            a.nav-link

Sempre use aspas simples.

//- Bom
button.btn(data-component='collapse')

//- Ruim
button.btn(data-component="collapse")

Insira o título do bloco, separe usando duas linhas em branco e agrupe os elementos internos do bloco.

//- Bom
 
//- Header
//- ===================================
header.header(role='banner')
  a.logo(href='#', role='logo')


//- Main
//- ===================================
main.main(role='main')
  section.content
 
//- Ruim
header.header(role='banner')
  a.logo(href='#', role='logo') 
main.main(role='main') 
  section.content

3.2. Pug Comentários

Siga esta regra para adicionar comentários no HTML.

//- Esse é um bom exemplo

// Esse é um exemplo ruim

Os comentários usando //- não são compilados no código final.

3.3. Pug Base Code

O código a seguir é uma base em Pug para iniciar rápidamente os projetos.

doctype html
html(lang='en')
  head 
    meta(charset='utf-8')
    meta(name='description', content='')
    meta(name='viewport', content='width=device-width, initial-scale=1.0, user-scalable=no')
    meta(name='format-detection', content='telephone=no')

    //- Title
    //- ===================================
    title 

    //- Favicon and SVG logo
    //- ===================================
    link(rel='shortcut icon', href='ico/favicon.ico')  
    link(rel='logo', type='image/svg', href='svg/logo/logo.svg')

    //- Stylesheet and fonts
    //- ===================================
    link(href='css/style.css', rel='stylesheet')  

  body

4. CSS

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

CSS Sumário

  1. CSS Sintaxe
  2. CSS Ordem de Declaração
  3. CSS Nome das Classes
  4. CSS Performance
  5. CSS Media Queries
  6. CSS Comentários

4.1. CSS Sintaxe

Use soft-tabs com dois espaços. Você pode configurar o seu editor 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
}

Mantenha uma declaração por linha.

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

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

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

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

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

Separe as regras por uma linha em branco.

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

.selector-2 {
  ...
}

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

Use 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;
}

4.2. CSS Ordem de Declaração

As declarações devem ser adicionadas em ordem alfabética.

/* Bom */
.selector-1 {
  background: #fff;
  border: #333 solid 1px;
  color: #333;
  display: block;
  height: 200px;
  margin: 5px;
  padding: 5px;
  width: 200px;
}

/* Ruim */
.selector-1 {
  padding: 5px;
  height: 200px;
  background: #fff;
  margin: 5px;
  width: 200px;
  color: #333;
  border: #333 solid 1px;
  display: block;
}

4.3. CSS Nome das Classes

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

/* Bom */
.page-header { ... }

/* Ruim */
.pageHeader { ... }
.page_header { ... }

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

/* Bom */
.navbar { ... }
.nav { ... }
.nav__item { ... }
.nav__link { ... }

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

Use um hífem para separar o nome do elemento, dois underlines para separar o bloco e dois hífens para separar o modificador de estilo.

/* Bom */
.page-header__action { ... }
.page-header__action__title { ... }
.page-header--active { ... }

.btn { ... }
.btn--primary { ... }

/* Ruim */
.page-header-action { ... }
.page-header-action-title { ... }
.page-header-active { ... }

.btn { ... }
.btn-primary { ... }

Evite usar nomes muito curtos e sempre use nomes relacionados com a função da classe.

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

/* Ruim */
.s { ... }
.ph { ... }
.block { ... }

4.4. CSS Performance

Nunca use IDs.

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

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

Não use 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 Grunt tornam isso muito mais fácil.

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

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

4.5 Mobile First and Media Queries

Comece o desenvolvimento usando regras genéricas e adiciona 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. Não coloque em documentos separados ou no fim do stylesheet.

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

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

4.7. 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

5. CSS Pré-processadores

Eu uso pré-processadores em todos os projetos. Atualmente estou usando Stylus, mas alguns projetos usam LESS.

CSS Pré-processadores Sumário

  1. CSS Pré-processadores Sintaxe
  2. CSS Pré-processadores Performance
  3. CSS Pré-processadores Media Queries
  4. CSS Pré-processadores Comentários

5.1. CSS Pré-processadores Sintaxe

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

// Bom
.nav-item 
  display inline-block  

// Ruim
.nav-item 
    display inline-block

Não use ponto e vírgula, dois pontos ou colchetes.

// Bom
.header 
  position fixed
  top 0
  right 0
  left 0

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

Mantenha uma declaração 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.

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

5.2. CSS Pré-processadores Performance

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

// Bom
.nav-item 
  ...

// Ruim
.navbar 
  .nav 
    .nav-item 
      ...

Não use @extends, sempre use mixins.

reset(arg = '')
  
  if (arg == list) 
    margin 0
    padding-left 0
    list-style none
    
  if (arg == form)  
    background 0
    border 0
    padding 0

.nav
  reset(list)

.btn
  reset(form)

5.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

5.4. CSS Pré-processadores Comentários

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

//  
// Variables
//
// 1. Colors
// 2. Spaces 
// 3. Media Queries 
// 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
...

6. 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

  1. JavaScript Sintaxe
  2. JavaScript Variáveis
  3. JavaScript Performance
  4. JavaScript e HTML5 Data Attributes
  5. JavaScript Comentários

6.1. JavaScript Sintaxe

Use soft-tabs com dois espaços. Você pode configurar o seu editor 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 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
}

6.2. JavaScript Variáveis

Todas as variáveis devem ser declaradas antes de usar.

// 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);

6.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 Grunt tornam isso muito mais fácil.

6.4. JavaScript and HTML5 Data Attributes

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

// Bom
$('[data-component="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.

6.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

7. Boilerplate

Eu tenho um boilerplate usando esse coding style.

Ele chama Kratos Boilerplate.

8. Referências

9. Traduções