Princpios para escrever CSS de forma consistente e idiomtica

O documento a seguir descreve um sensato guia de estilo para desenvolvimento CSS. No pretendo ser prescritivo e no quero impor as minhas preferncias de estilo no cdigo de outras pessoas. Entretanto, estas orientaes incentivam fortemente o uso de existentes, comuns e sensatos padres. Esse um documento vivo e novas ideias so sempre bem-vindas. Por favor contribua. Idiomatic CSS em Ingls (Original)

ndice
1. Princpios gerais 2. Espaos em branco 3. Comentrios 4. Formatao 5. Nomeando 6. Exemplo prtico 7. Organizao 8. Build e deploy 9. Agradecimentos

1. Princpios gerais
"Parte de ser um bom gestor de um projeto bem sucedido perceber que escrever cdigo para si mesmo uma M Ideia. Se milhares de pessoas esto usando o seu cdigo, ento escreva-o com mxima clareza, no sob a sua preferncia pessoal de como ser esperto com a especificao." - Idan Gazit

Todo cdigo em qualquer aplicao deve parecer como se tivesse sido escrito por uma nica pessoa, independentemente de quantas pessoas tenham contribudo. Faa cumprir rigorosamente o estilo acordado. Em caso de dvida, utilizar padres existentes e comuns.

2. Espaos em branco
Apenas um estilo deve existir em todo o projeto. Seja sempre consistente na utilizao de espaos em branco. Use espaos em branco para melhorar a legibilidade.

Nunca misture espaos e tabs para indentao. Escolha entre indentao suave (espaos) ou tabulao. Atenha-se sua escolha sem falhar. (Preferncia: espaos) Se usar espaos, escolha o nmero de caracteres usados por nvel de indentao. (Preferncia: 4 espaos)

Dica: configure seu editor para "mostrar invisveis". Isso ir permitir que voc elimine espaos em branco da quebra de linha, elimine espaos em branco de linhas vazias sem indentao e evite commits poludos.

3. Comentrios
Cdigo bem comentado extremamente importante. Tire tempo para descrever componentes, como eles funcionam, suas limitaes, e o modo como so construdos. No deixe outros no time adivinharem o propsito de cdigos incomuns ou no bvios. Estilo de comentrio deve ser simples e consistente dentro de uma nica base de cdigo.

Coloque comentrios em uma nova linha acima do seu assunto. Evite comentrios no fim da linha. Mantenha o comprimento da linha a um mximo sensvel, por exemplo, 80 colunas. Faa o uso liberal de comentrios para quebrar o cdigo CSS em sees distintas. Use comentrios com iniciais maisculas e indentao de texto consistente.

Dica: configure seu editor para lhe prover com atalhos a gerao do padro de comentrios acordado.

exemplo com CSS:

/* ========================================================================== Bloco de comentrio de seo ========================================================================== */ /* Bloco de comentrio de sub-seo ========================================================================== */ /* * Bloco de comentrio de grupo * Ideal para explicaes em mltiplas linhas e documentao. */ /* Comentrio bsico */

exemplo com SCSS:

// ========================================================================== // Bloco de comentrio de seo // ========================================================================== // Bloco de comentrio de sub-seo // ========================================================================== // // Bloco de comentrio de grupo

// Ideal para explicaes em mltiplas linhas e documentao. // // Comentrio bsico

4. Formatao
O formato de cdigo escolhido deve garantir que o cdigo seja: fcil de ler; fcil de comentar claramente; minimize a chance de introduzir erros acidentalmente; e resulte em teis visualizaes de diferena. 1. Um seletor discreto por linha em um conjunto de regras com multi-seletores. 2. Um nico espao antes da abertura das chaves em um conjunto de regras. 3. Uma nica declarao por linha em um bloco de declarativo. 4. Um nvel de indentao para cada declarao. 5. Um nico espao depois dos dois pontos de uma declarao. 6. Sempre inclua um ponto-e-vrgula no fim da ltima declarao 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.

.selector-1, .selector-2, .selector-3 { -webkit-box-sizing: border-box; -moz-box-sizing: border-box; box-sizing: border-box; display: block; color: #333; background: #fff; }

Ordem de declarao
Declaraes devem ser ordenadas segundo um nico princpio. Minha preferncia por propriedades relacionadas para serem agrupadas e por propriedades estruturalmente importantes (por exemplo, posicionamento e box-model) para serem declaradas antes de propriedades tipogrficas, fundo ou cor.
.selector { position: relative; display: block; width: 50%; height: 100px; padding: 10px; border: 0; margin: 10px; color: #fff

background: #000; }

Ordenao alfabtica tambm popular, mas a desvantagem que ela separa as propriedades relacionadas. Por exemplo, deslocamentos de posio no so mais agrupados e propriedades do boxmodel podem acabar propagando ao longo de um bloco de declarao.

Excees e ligeiros desvios

Grandes blocos de declaraes individuais podem atuar de forma diferente, atravs da formatao de linha nica. Nesse caso, um espao deve ser considerado depois da abertura das chaves e antes do fechamento das chaves.
.selector-1 { width: 10%; } .selector-2 { width: 20%; } .selector-3 { width: 30%; }

Longos valores de propriedades separados por vrgula - como colees de degrads ou sombras podem ser organizados em vrias linhas em um esforo para melhorar a legibilidade e produz visualizaes de diferena mais teis. Existem vrios formatos que poderiam ser usados; um exemplo mostrado abaixo.
.selector { box-shadow: 1px 1px 1px #000, 2px 2px 1px 1px #ccc inset; background-image: linear-gradient(#fff, #ccc), linear-gradient(#f3c, #4ec); }

Miscelnea

Use valores hexadecimais em letras minsculas, por exemplo: #aaa . Use aspas simples ou duplas de forma consistente. Preferncia por aspas duplas, por exemplo: content: "" . Sempre coloque aspas em valores de atributos nos seletores, por exemplo: input[type="checkbox"] . Onde permitido, evite especificar unidades para valores-zero, por exemplo: margin: 0 .

Pr-processadores: consideraes de formatao adicionais

Diferentes pr-processadores de CSS possuem diferentes caractersticas, funcionalidades e sintaxe. Suas convenes devem ser extendidas para acomodar as particularidades de qualquer prprocessador em uso. As seguintes diretrizes so em referncia ao Sass.

Limite o aninhamento a 1 nvel de profundidade. Reavalie qualquer aninhamento que tenha mais de 2 nveis de profundidade. Isso impede que existam seletores CSS muito especficos. Evite um grande nmero de regras aninhadas. Quebre-os para quando a legibilidade comear a ser afetada. Preferncia por evitar aninhamentos que se espalhem por mais de 20 linhas. Sempre coloque as declaraes @extend nas primeiras linhas de um bloco declarativo. Quando possvel, agrupe declaraes @include no topo de blocos declarativos, depois de qualquer declarao @extend . Considere funes customizadas para prefixos com x- ou qualquer namespace. Isso ajuda a evitar qualquer potencial confuso na sua funo com a funo de CSS nativo ou de colidir com funes de bibliotecas.

.selector-1 { @extend .other-rule; @include clearfix(); @include box-sizing(border-box); width: x-grid-unit(1); // other declarations }

5. Nomeando
Voc no um compilador/compressor de cdigo humano, ento no tente ser. Use nomes claros e previdentes para classes HTML. Escolha um padro de nomes compreensvel e consistente que faa sentido para arquivos HTML e arquivos CSS.
/* Exemplo de cdigo com nomes ruins */ .s-scr { overflow: auto; } .cb { background: #000; } /* Exemplo de cdigo com bons nomes */ .is-scrollable { overflow: auto; } .column-body { background: #000; }

6. Exemplo prtico
Um exemplo de vrias convenes.
/* ========================================================================== Grid layout ========================================================================== */ /* * Exemplo de HTML: * * <div class="grid"> * <div class="cell cell-5"></div> * <div class="cell cell-5"></div> * </div> */ .grid { overflow: visible; height: 100%; /* Prevent inline-block cells wrapping */ white-space: nowrap; /* Remove inter-cell whitespace */ font-size: 0; } .cell { box-sizing: border-box; position: relative; overflow: hidden; width: 20%; height: 100%; /* Set the inter-cell spacing */ padding: 0 10px; border: 2px solid #333; vertical-align: top; /* Reset white-space */ white-space: normal; /* Reset font-size */ font-size: 16px; } /* Cell states */ .cell.is-animating { background-color: #fffdec; }

/* Cell dimensions ========================================================================== */ .cell-1 .cell-2 .cell-3 .cell-4 .cell-5 { { { { { width: width: width: width: width: 10%; 20%; 30%; 40%; 50%; } } } } }

/* Cell modifiers ========================================================================== */ .cell--detail, .cell--important { border-width: 4px; }

7. Organizao
Organizao de cdigo uma importante parte de qualquer base de cdigo CSS, e crucial para grandes bases de cdigo.

Separar logicamente distintas partes do cdigo. Usar arquivos separados (concatenados por um processo de build) para ajudar a dividir cdigo para componentes distintos. Se estiver usando um pr-processador, abstrair partes comuns de cdigo em variveis para cor, tipografia, etc.

8. Build e deploy
Os projetos devem sempre tentar incluir alguns meios genricos pelos quais sua fonte possa ser avaliada, testada, comprimida e versionada em preparao para uso em produo. Para essa tarefa, o grunt por Ben Alman uma excelente ferramenta.

Agradecimentos
Obrigado a todos que contribuiram para idiomatic.js. Foi uma fonte de inspirao, citaes e diretrizes.