"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.
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"A principal influencia das regras de HTML é o Code Guide by @mdo.
- HTML Sintaxe
- HTML Comentários
- HTML Encoding de Caracteres
- HTML Ordem dos Atributos
- HTML Performance
- HTML Código Base
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>Siga esta regra para adicionar comentários no HTML.
<!-- Este é um bom exemplo -->
<!-- /Fechando um bom exemplo -->Sempre use UTF-8 para encoding de caracteres.
<head>
<meta charset="UTF-8">
</head>Os atributos do HTML devem estar na seguinte ordem para facilitar a leitura.
classid,namedata-*src,for,type,hreftitle,altaria-*,role
<a class="..." id="..." data-modal="#overlay" href="#">
<input class="form-control" type="text">
<img class="img-rounded" src="..." alt="...">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>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>
...Atualmente usando Pug como template engine.
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-linkSempre 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.contentSiga esta regra para adicionar comentários no HTML.
//- Esse é um bom exemplo
// Esse é um exemplo ruimOs comentários usando //- não são compilados no código final.
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 A principal influencia para as regras de CSS são o Code Guide by @mdo e o idiomatic CSS.
- CSS Sintaxe
- CSS Ordem de Declaração
- CSS Nome das Classes
- CSS Performance
- CSS Media Queries
- CSS Comentários
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;
}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;
}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 { ... }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
sectionEvite 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 {
...
}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 { ... }
}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 simplesEu uso pré-processadores em todos os projetos. Atualmente estou usando Stylus, mas alguns projetos usam LESS.
- CSS Pré-processadores Sintaxe
- CSS Pré-processadores Performance
- CSS Pré-processadores Media Queries
- CSS Pré-processadores Comentários
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 leftUse $ para as váriaveis.
// Good
$gray-darker = #111
$gray-dark = #393C45
$gray = #555
$gray-light = #aaa
$gray-lighter = #ECF1F5
$gray-white = #fbfbfb 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)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 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
...As principais influencias para as regras de escrita em JavaScript são o idiomatic.js e o Zeno Rocha Coding Style.
- JavaScript Sintaxe
- JavaScript Variáveis
- JavaScript Performance
- JavaScript e HTML5 Data Attributes
- JavaScript Comentários
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
}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);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.
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.
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árioEu tenho um boilerplate usando esse coding style.
Ele chama Kratos Boilerplate.