Normas de codificación CSS de Bootstrap

Sintaxis

  • Usa dos espacios en lugar de tabulaciones (tab): es la única forma de garantizar una presentación coherente en todos los entornos.
  • Al agrupar selectores, coloca cada selector individual en una línea separada.
  • Para mejorar la legibilidad del código, añade un espacio antes de la llave de apertura de cada bloque de declaraciones.
  • La llave de cierre del bloque de declaraciones debe ir en una línea separada.
  • Después de los dos puntos de cada declaración:se debe insertar un espacio.
  • Para obtener informes de errores más precisos, cada declaración debe ocupar su propia línea.
  • Todas las declaraciones deben terminar con punto y coma. El punto y coma después de la última declaración es opcional; sin embargo, si se omite, tu código puede ser más propenso a errores.
  • Para los valores de propiedades separados por comas, se debe insertar un espacio después de cada coma (por ejemplo,box-shadow）。
  • No insertes un espaciorgb()、rgba()、hsl()、hsla()orect()después de la coma en el interiorde los valoresde color. Esto ayuda a distinguir entre los múltiples valores de propiedad (que llevan coma y espacio) y los múltiples valores de color (que solo llevan coma, sin espacio).
  • Para valores de propiedades o parámetros de color, omite el 0 a la izquierda de los decimales menores que 1 (por ejemplo,.5en lugar de0.5；-.5pxen lugar de-0.5px）。
  • Los valores hexadecimales deben escribirse completamente en minúsculas, por ejemplo,#fffAl examinar el documento, los caracteres en minúsculas son más fáciles de distinguir porque sus formas son más reconocibles.
  • Usa en la medida de lo posible valores hexadecimales abreviados, por ejemplo, usa#fffen lugar de#ffffff。
  • Añade comillas dobles a los atributos dentro de los selectores, por ejemplo,input[type="text"]。solo son opcionales en ciertos casos,pero, por coherencia en el código, se recomienda usar siempre comillas dobles.
  • Evita especificar una unidad para el valor 0, por ejemplo, usamargin: 0;en lugar demargin: 0px;。

¿Te surgen dudas sobre los términos utilizados aquí? Consulta en Wikipedia la página sobreHojas de Estilo en Cascada - Sintaxis。

/* Bad CSS */
.selector, .selector-secondary, .selector[type=text] {
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0, 0, 0, 0.5);
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}

/* Good CSS */
.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgba(0,0,0,.5);
  box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}

Orden de las declaraciones

Las declaraciones de propiedades relacionadas deben agruparse y ordenarse de la siguiente manera:

  1. Positioning
  2. Box model
  3. Typographic
  4. Visual

El posicionamiento (positioning) va primero porque puede extraer elementos del flujo normal del documento y también puede sobrescribir los estilos relacionados con el modelo de caja (box model). El modelo de caja va en segundo lugar porque determina el tamaño y la posición del componente.

El resto de propiedades solo afectan alinterior (inside)o no afectan a los dos primeros grupos de propiedades, por lo que se colocan al final.

Consulta la lista completa de propiedades y su orden enRecess。

.declaration-order {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typography */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Visual */
  background-color: #F5F5F5;
  border: 1px solid #E5E5E5;
  border-radius: 3px;

  /* Misc */
  opacity: 1;
}

No utilizar@import

y<link>En comparación con la etiqueta `<link>`,@importla directiva es mucho más lenta; no solo aumenta el número de solicitudes adicionales, sino que también puede ocasionar problemas imprevistos. Existen varias alternativas:

  • Utilizar múltiples<link>elementos `<link>`
  • Compilar varios archivos CSS en un solo archivo mediante un preprocesador de CSS como Sass o Less
  • Utilizar la función de fusión de archivos CSS proporcionada por Rails, Jekyll u otros sistemas

Consultael artículo de Steve Souderspara obtener más información.

<!-- Use link elements -->
<link rel="stylesheet" href="core.css.html">

<!-- Avoid @imports -->
<style>
  @import url("more.css");
</style>

Ubicación de las consultas de medios (media queries)

Coloca las consultas de medios lo más cerca posible de las reglas relacionadas. No las empaquetes en un solo archivo de estilos ni las coloques al final del documento. Si las separas, acabarán olvidadas por todos. A continuación se muestra un ejemplo típico.

.element { ... }
.element-avatar { ... }
.element-selected { ... }

@media (min-width: 480px) {
  .element { ...}
  .element-avatar { ... }
  .element-selected { ... }
}

Propiedades con prefijo

Cuando utilices propiedades con prefijo de un proveedor específico, alinea verticalmente los valores de cada propiedad mediante la sangría; así se facilita la edición de varias líneas.

En TextMate, usaText → Edit Each Line in Selection(⌃⌘A). En Sublime Text 2, usaSelection → Add Previous Line(⌃⇧↑) ySelection → Add Next Line (⌃⇧↓).

/* Prefixed properties */
.selector {
  -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
          box-shadow: 0 1px 2px rgba(0,0,0,.15);
}

Declaraciones de reglas en una sola línea

Paralos estilos que solo contienen una declaración,se recomienda poner la declaración en una misma línea para facilitar la lectura y la edición rápida. Para los estilos con varias declaraciones, estas deben dividirse en varias líneas.

El factor clave de esta práctica es la detección de errores. Por ejemplo, si el validador de CSS señala un error de sintaxis en la línea 183, con una declaración por línea no pasarás por alto ese error; con varias declaraciones en una línea, tendrás que analizar con cuidado para no omitirlo.

/* Single declarations on one line */
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

/* Multiple declarations, one per line */
.sprite {
  display: inline-block;
  width: 16px;
  height: 15px;
  background-image: url(../img/sprite.png);
}
.icon           { background-position: 0 0; }
.icon-home      { background-position: 0 -20px; }
.icon-account   { background-position: 0 -40px; }

Declaraciones abreviadas de propiedades

Cuando sea necesario establecer explícitamente todos los valores, se debe limitar el uso de declaraciones abreviadas. Los casos más comunes de abuso de este tipo de declaraciones son los siguientes:

  • padding
  • margin
  • font
  • background
  • border
  • border-radius

En la mayoría de los casos no es necesario especificar todos los valores de una declaración abreviada. Por ejemplo, los elementos de encabezado (heading) de HTML solo necesitan definir los valores de los márgenes (margin) superior e inferior; por lo tanto, cuando sea necesario, basta con sobrescribir esos dos valores. El uso excesivo de declaraciones abreviadas hace que el código sea confuso y provoca sobrescrituras innecesarias de valores de propiedad, lo que puede causar efectos secundarios inesperados.

MDN (Mozilla Developer Network) tiene un artículo muy bueno sobreshorthand propertiesque resulta muy útil para quienes no estén familiarizados con las declaraciones abreviadas y su comportamiento.

/* Bad example */
.element {
  margin: 0 0 10px;
  background: red;
  background: url("image.jpg");
  border-radius: 3px 3px 0 0;
}

/* Good example */
.element {
  margin-bottom: 10px;
  background-color: red;
  background-image: url("image.jpg");
  border-top-left-radius: 3px;
  border-top-right-radius: 3px;
}

Anidamiento en Less y Sass

Evita el anidamiento innecesario. Aunque puedas usar el anidamiento, no significa que debas hacerlo. Úsalo solo cuando sea necesario restringir los estilos al elemento padre (es decir, un selector de descendientes) y existan varios elementos que deban anidarse.

// Without nesting
.table > thead > tr > th { … }
.table > thead > tr > td { … }

// With nesting
.table > thead > tr {
  > th { … }
  > td { … }
}

Comentarios

El código lo escriben y mantienen personas. Asegúrate de que tu código sea autodescriptivo, esté bien comentado y sea fácil de entender para los demás. Un buen comentario transmite el contexto y el propósito del código. No te limites a repetir el nombre del componente o de la clase.

Escribe oraciones completas en los comentarios largos; para anotaciones generales, puedes usar frases breves.

/* Bad example */
/* Modal header */
.modal-header {
  ...
}

/* Good example */
/* Wrapping element for .modal-title and .modal-close */
.modal-header {
  ...
}

Nomenclatura de clases (class)

  • Los nombres de clase solo pueden contener caracteres en minúscula y guiones (dashes), no guiones bajos ni nomenclatura camelCase. Los guiones deben usarse para nombrar clases relacionadas (similar a un espacio de nombres) (por ejemplo,.btny.btn-danger）。
  • Evita abreviaciones excesivamente arbitrarias..btnrepresentabutton, pero.sno expresa ningún significado.
  • Los nombres de clase deben ser lo más breves posible y, a la vez, tener un significado claro.
  • Utiliza nombres significativos. Utiliza nombres organizativos o que reflejen su propósito, evitando nombres de presentación (presentational).
  • Usa la clase padre más cercana o la clase base (base) como prefijo de las nuevas clases.
  • Usa.js-*clases para identificar el comportamiento (a diferencia del estilo) y no incluyas estas clases en los archivos CSS.

Al nombrar variables de Sass y Less, también puedes consultar las normas enumeradas anteriormente.

/* Bad example */
.t { ... }
.red { ... }
.header { ... }

/* Good example */
.tweet { ... }
.important { ... }
.tweet-header { ... }

Selectores

  • Usa clases para elementos genéricos; esto favorece la optimización del rendimiento del renderizado.
  • Para componentes que aparecen con frecuencia, evita usar selectores de atributos (por ejemplo,[class^="..."]). El rendimiento del navegador puede verse afectado por estos factores.
  • Los selectores deben ser lo más cortos posible; limita también el número de elementos que componen el selector; se recomienda que no superen 3.
  • Solocuando sea necesario se deben restringir las clases al elemento padre más cercano (es decir, un selector de descendientes) (por ejemplo, cuando no se usan clases con prefijo, ya que el prefijo actúa como espacio de nombres).

Lecturas complementarias:

/* Bad example */
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

/* Good example */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

Organización del código

  • Organiza los bloques de código por componentes.
  • Define una convención de comentarios coherente.
  • Usa espacios en blanco consistentes para dividir el código en bloques; esto facilita el escaneo de documentos grandes.
  • Si se usan varios archivos CSS, divídelos por componentes en lugar de por páginas, porque las páginas se reorganizan, mientras que los componentes solo se mueven.
/*
 * Component section heading
 */

.element { ... }


/*
 * Component section heading
 *
 * Sometimes you need to include optional context for the entire component. Do that up here if it's important enough.
 */

.element { ... }

/* Contextual sub-component or modifer */
.element-heading { ... }

Configuración del editor

Configura tu editor de la siguiente manera para evitar inconsistencias y diferencias comunes en el código:

  • Usa dos espacios en lugar de tabulaciones (soft-tab, es decir, usar espacios para representar el tabulador).
  • Al guardar el archivo, elimina los espacios en blanco al final de la línea.
  • Configura la codificación del archivo como UTF-8.
  • Añade una línea en blanco al final del archivo.

Consulta la documentación y añade estas opciones de configuración al.editorconfigarchivo del proyecto. Por ejemplo:Ejemplo de `.editorconfig` en Bootstrap. Para más información, consultaabout EditorConfig。

Otras extensiones