14 de fevereiro de 2012 CSS3

Princípios para escrever CSS de forma consistente

Pra você que não aguenta mais ver código bagunçado

Por Zeno Rocha

Um problema muito comum quando trabalhamos em equipe é a inconsistência no estilo de codificação. Uns preferem colocar as propriedades do CSS em uma única linha, outros não. Uns gostam de colocar espaço depois dos dois-pontos, outros não. No fim, acaba tudo uma zona. São muitos desenvolvedores, escrevendo de formas totalmente distintas, o que prejudica qualquer tipo de manutenção ou evolução do código.

Por isso, tenho notado um movimento cada vez maior de empresas buscando padronizar seu estilo de código. Google, Github e muitas outras já disponibilizaram publicamente seus guias de estilo:

• Google HTML/CSS Style Guide
• Github CSS/JS/Ruby Style Guide

Pensando nisso, Nicolas Gallagher (@necolas), funcionário do Twitter, criador do Normalize.css e um dos líderes do HTML5 Boilerplate, resolveu criar um guia chamado Idiomatic CSS – Princípios para escrever CSS de forma consistente e idiomática. Baseado em um projeto semelhante, porém com foco em JavaScript, o idiomatic.js.

O que eu irei apresentar hoje é uma pequena adaptação da tradução oficial, feita por mim, desse documento vivo e aberto para contribuições através do Github.

O guia a seguir não pretende ser prescritivo e também não busca impor as preferências do autor no código de outras pessoas. Entretanto, estas orientações incentivam fortemente o uso de padrões já existentes, comuns e sensatos.

1. Princípios gerais

Todo código em qualquer aplicação deve parecer como se tivesse sido escrito por uma única pessoa, independentemente de quantas pessoas tenham contribuído. Faça cumprir rigorosamente o estilo acordado.

2. Espaços em branco

Novamente, apenas um estilo deve existir em todo o projeto. Seja sempre consistente na utilização de espaços em branco. Use espaços em branco para melhorar a legibilidade.

• Nunca misture espaços e tabs para indentação.
• Escolha entre indentação suave (espaços) ou tabulação. Atenha-se à sua escolha sem falhar. (Preferência: espaços)
• Se usar espaços, escolha o número de caracteres usados por nível de indentação. (Preferência: 4 espaços)

Dica: configure seu editor para “mostrar invisíveis”. Isso irá permitir que você elimine espaços em branco da quebra de linha, elimine espaços em branco de linhas vazias sem indentação e evite commits poluídos.

3. Comentários

Código bem comentado é extremamente importante. Tire tempo para descrever componentes, como eles funcionam, suas limitações e o modo como são construídos. Não deixe outros no time adivinharem o propósito de códigos incomuns ou não óbvios.

Estilo de comentário deve ser simples e consistente dentro de uma única base de código.

• Coloque comentários em uma nova linha acima do seu assunto.
• Evite comentários no fim da linha.
• Mantenha o comprimento da linha a um máximo sensível, por exemplo, 80 colunas.
• Faça o uso liberal de comentários para quebrar o código CSS em seções distintas.
• Use comentários com iniciais maiúsculas e indentação de texto consistente.

Dica: configure seu editor para lhe prover com atalhos a geração do padrão de comentários acordado.

Exemplo com CSS:

[cc lang="css"]
/* ==========================================================================
Bloco de comentário de seção
========================================================================== */

/* Bloco de comentário de sub-seção
========================================================================== */

/*
* Bloco de comentário de grupo
* Ideal para explicações em múltiplas linhas e documentação.
*/

/* Comentário básico */
[/cc]

Exemplo com SCSS:

[cc lang="css"]
// ==========================================================================
// Bloco de comentário de seção
// ==========================================================================

// Bloco de comentário de sub-seção
// ==========================================================================

//
// Bloco de comentário de grupo
// Ideal para explicações em múltiplas linhas e documentação.
//

// Comentário básico
[/cc]

4. Formatação

O formato de código escolhido deve garantir que o código seja: fácil de ler; fácil de comentar claramente; minimize a chance de introduzir erros acidentalmente; e resulte em úteis visualizações de diferença.

1. Um seletor discreto por linha em um conjunto de regras com multi-seletores.
2. Um único espaço antes da abertura das chaves em um conjunto de regras.
3. Uma única declaração por linha em um bloco de declarativo.
4. Um nível de indentação para cada declaração.
5. Um único espaço depois dos dois pontos de uma declaração.
6. Sempre inclua um ponto-e-vírgula no fim da última declaração em um bloco declarativo.
7. Coloque o fechamento das chaves na mesma coluna que o primeiro caracter do conjunto de regras.
8. Separe cada conjunto de regras por uma linha em branco.

[cc lang="css"]
.seletor-1,
.seletor-2,
.seletor-3 {
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
display: block;
color: #333;
background: #fff;
}[/cc]

Ordem de declaração

Declarações devem ser ordenadas segundo um único princípio. Minha preferência é por propriedades relacionadas para serem agrupadas e por propriedades estruturalmente importantes (por exemplo, posicionamento e box-model) para serem declaradas antes de propriedades tipográficas, fundo ou cor.

[cc lang="css"]
.seletor {
position: relative;
display: block;
width: 50%;
height: 100px;
padding: 10px;
border: 0;
margin: 10px;
color: #fff
background: #000;
}[/cc]

Ordenação alfabética também é popular, mas a desvantagem é que ela separa as propriedades relacionadas. Por exemplo, deslocamentos de posição não são mais agrupados e propriedades do box-model podem acabar propagando ao longo de um bloco de declaração.

Exceções e ligeiros desvios

Grandes blocos de declarações individuais podem atuar de forma diferente, através da formatação de linha única. Nesse caso, um espaço deve ser considerado depois da abertura das chaves e antes do fechamento das chaves.

[cc lang="css"]
.seletor-1 { width: 10%; }
.seletor-2 { width: 20%; }
.seletor-3 { width: 30%; }
[/cc]

Longos valores de propriedades separados por vírgula – como coleções de degradês ou sombras – podem ser organizados em várias linhas em um esforço para melhorar a legibilidade e produz visualizações de diferença mais úteis. Existem vários formatos que poderiam ser usados; um exemplo é mostrado abaixo.

[cc lang="css"]
.seletor {
box-shadow:
1px 1px 1px #000,
2px 2px 1px 1px #ccc inset;
background-image:
linear-gradient(#fff, #ccc),
linear-gradient(#f3c, #4ec);
}[/cc]

Miscelânea

Use valores hexadecimais em letras minúsculas, por exemplo: [cc lang="css"]#aaa[/cc]
Use aspas simples ou duplas de forma consistente. Preferência por aspas duplas, por exemplo: [cc lang="css"]content: “”[/cc]
Sempre coloque aspas em valores de atributos nos seletores, por exemplo: [cc lang="css"]input[type="checkout"][/cc]
Onde permitido, evite especificar unidades para valores-zero, por exemplo: [cc lang="css"]margin: 0[/cc]

Pré-processadores: considerações de formatação adicionais

Diferentes pré-processadores de CSS possuem diferentes características, funcionalidades e sintaxe. Suas convenções devem ser extendidas para acomodar as particularidades de qualquer pré-processador em uso. As seguintes diretrizes são em referência ao Sass.

• Limite o aninhamento a 1 nível de profundidade. Reavalie qualquer aninhamento que tenha mais de 2 níveis de profundidade. Isso impede que existam seletores CSS muito específicos.
• Evite um grande número de regras aninhadas. Quebre-os para quando a legibilidade começar a ser afetada. Preferência por evitar aninhamentos que se espalhem por mais de 20 linhas.
• Sempre coloque as declarações @extend nas primeiras linhas de um bloco declarativo.
• Quando possível, agrupe declarações @include no topo de blocos declarativos, depois de qualquer declaração @extend.
• Considere funções customizadas para prefixos com x- ou qualquer namespace. Isso ajuda a evitar qualquer potencial confusão na sua função com a função de CSS nativo ou de colidir com funções de bibliotecas.

[cc lang="css"]
.seletor-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// outras declarações
}[/cc]

5. Nomeando

Você não é um compilador/compressor de código humano, então não tente ser.

Use nomes claros e previdentes para classes HTML. Escolha um padrão de nomes compreensível e consistente que faça sentido para arquivos HTML e arquivos CSS.

[cc lang="css"]
/* Exemplo de código com nomes ruins */

.s-scr {
overflow: auto;
}

.cb {
background: #000;
}

/* Exemplo de código com bons nomes */

.is-scrollable {
overflow: auto;
}

.column-body {
background: #000;
}[/cc]

6. Exemplo prático

Um exemplo de várias convenções.

[cc lang="css"]
/* ==========================================================================
Grid layout
========================================================================== */

/*
* Exemplo de HTML:
*
*

*/

.grid {
overflow: visible;
height: 100%;
white-space: nowrap;
font-size: 0;
}

.cell {
box-sizing: border-box;
position: relative;
overflow: hidden;
width: 20%;
height: 100%;
padding: 0 10px;
border: 2px solid #333;
vertical-align: top;
white-space: normal;
font-size: 16px;
}

/* Células – Estados */

.cell.is-animating {
background-color: #fffdec;
}

/* Células – Dimensões
========================================================================== */

.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }

/* Células – Modificadores
========================================================================== */

.cell–detail,
.cell–important {
border-width: 4px;
}
[/cc]

7. Organização

Organização de código é uma importante parte de qualquer base de código CSS, e crucial para grandes bases de código.

• Separar logicamente distintas partes do código.
• Usar arquivos separados (concatenados por um processo de build) para ajudar a dividir código para componentes distintos.
• Se estiver usando um pré-processador, abstrair partes comuns de código em variáveis para cor, tipografia, etc.

8. Build e deploy

Os projetos devem sempre tentar incluir alguns meios genéricos pelos quais sua fonte possa ser avaliada, testada, comprimida e versionada em preparação para uso em produção. Para essa tarefa, o grunt por Ben Alman é uma excelente ferramenta.

Conclusão

Independemente de você ter concordado ou não com o guia de estilo proposto, o importante é entender como uma padronização no estilo do código pode ajudar você e sua equipe. Pense nisso.