Guía de Código por @mdo

Estándares para desarrollar HTML y CSS, flexibles, duraderos y sustentables.

Tabla de contenidos

HTML

CSS

Regla de oro

Cumple con estas o con tus reglas propias aceptadas, siempre. Pequeño o grande, has notar lo que está incorrecto. Para añadir o contribuir a esta Guía de Código, por favor abre un issue en GitHub.

Cada línea de código debe parecer haber sido escrita por una sola persona, no importa el número de contribuidores.

HTML

Sintaxis

<!DOCTYPE html>
<html>
  <head>
    <title>Page title</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Company">
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>

HTML5 doctype

Haz cumplir los estándares y los más consistentes modos de interpretación en cada navegador posible con este simple doctype al principio de cada página HTML.

<!DOCTYPE html>
<html>
  <head>
  </head>
</html>

Atributo de lenguaje

De la especificación HTML5:

Los autores son alentados a especificar un atributo de lenguaje en la raíz del elemento html, para dar el lenguaje del documento. Esto ayuda a que las herramientas de síntesis de voz determinen que pronunciación usar, a las herramientas de traducción que reglas usar y así sucesivamente.

Lee más sobre el atributo lang en la especificación.

Dirigete a Sitepoint para una lista códigos de lenguaje.

<html lang="en-us">
  <!-- ... -->
</html>

Modo de compatibilidad con IE

Internet Explorer soporta el uso de una etiqueta de compatibilidad de documento <meta> para especificar que versión de IE se debería usar para interpretar la página. A menos que las circunstancias lo requieran de otra manera, es más útil darle la instrucción a IE de usar la modalidad más actual con la modalidad edge.

Para más información, lee este asombroso artículo de Stack Overflow.

<meta http-equiv="X-UA-Compatible" content="IE=Edge">

Códificación de caracteres

De manera rápida y fácil asegura la correcta interpretación de tu contenido decladarando de manera explícita una códificación de caracteres. Al hacerlo, puede que evites el uso de entidades de caracteres en tu código HTML, siempre y cuando su codificación coincida con la del documento (generalmente UTF-8)

<head>
  <meta charset="UTF-8">
</head>

Etiquetas para CSS y JavaScript

Por especificaciones de HTML5, normalmente no hay necesidad de especificar el type cuando incluyes archivos CSS y JavaScript porque text/css y text/javascript son sus respectivos valores estándar.

HTML5 spec links

<!-- External CSS -->
<link rel="stylesheet" href="code-guide.css">

<!-- In-document CSS -->
<style>
  /* ... */
</style>

<!-- JavaScript -->
<script src="code-guide.js"></script>

Practicidad antes que la pureza

Esfuérzate por mantener los estándares y la semántica de HTML, pero no a expensas de la practicidad. Usa la menor cantidad de marcado con la menor complejidad posible.

Orden de los atributos

Los atributos HTML deben venir este orden en particular para que el código sea más fácil de leer.

Las clases son excelentes para componentes reutilizables, así que ellas van primero. Los ids son más especificos y deberían usarse en menor medida (v.g., para los marcadores dentro de la página), así que ellos van en segundo lugar.

<a class="..." id="..." data-modal="toggle" href="#">
  Example link
</a>

<input class="form-control" type="text">

<img src="..." alt="...">

Atributos booleanos

Un atributo booleano es uno que no necesita valor declarado. XHTML requería que declararas un valor, pero HTML5 no tiene ese requerimiento.

Para mayor información, consulta la sección de WhatWG sobre atributos booleanos:

La presencia de un atributo booleano en un elemento representa el valor verdadero, y la ausencia del atributo representa el valor falso.

Si debes incluir el valor del atributo, y no lo necesitas, sigue esta pauta de WhatWG:

Si el atributo está presente, su valor debe ser un cadena vacía o [...] el nombre canónico del atributo, sin espacios en blanco al principio o al final.

En pocas palabras, no agregues un valor.

<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

Reduciendo el marcado

Cuando sea posible, evita elementos primarios superfluos al escribir HTML. Muchas veces esto requiere iteración y refactorización, pero produce menos HTML. Mira el siguiente ejemplo:

<!-- Not so great -->
<span class="avatar">
  <img src="...">
</span>

<!-- Better -->
<img class="avatar" src="...">

Marcado generado por JavaScript

Escribir marcado en un archivo JavaScript hace que el contenido sea más difícil de encontrar, más difícil de modificar y menos eficiente. Evita esto siempre que sea posible.

CSS

Sintaxis

¿Preguntas sobre los términos usados aquí? Revisa la sección de sintaxis del artículo de Hojas de estilo en cascada en Wikipedia.

/* 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 declaración

Declaraciones de propiedades relacionados deben agruparse siguiendo este orden:

  1. Posicionamiento
  2. Modelo de caja
  3. Tipografía
  4. Visual

Posicionamiento es lo primero, ya que puede eliminar un elemento del flujo normal del documento y reemplazar estilos relacionados con el modelo de caja. El modelo de caja viene a continuación, ya que determina las dimensiones y la colocación de un componente.

Todo lo demás toma lugar dentro del componente o sin impactar las dos secciones anteriores, y por lo tanto vienen al último.

Para obtener una lista completa de propiedades y su orden, por favor consulta Recess.

.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 uses @import

Comparado con los <link>s, @import es más lento, añade peticiones de página adicionales, y puede causar otros imprevistos. Evítalos y opta mejor por un enfoque diferente:

Para más información, lee este artículo de Steve Souders.

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

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

Colocación de consulta de medios Media Queries

Coloca Media Queries lo más cercano al grupo de reglas relevantes cuando sea posible. No las agrupes todas en una hoja de estilos separada o al final del documento. Al agrupar estas reglas, facilitas a que alguien las pase por alto en el futuro. Aquí está una configuración típica.

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

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

Propiedades prefijadas

Cuando uses los prefijos de navegadores, indenta cada propiedad de tal manera que el valor de la declaración se alinea verticalmente para facilitar la edición multi-línea

En Textmate, usa Text → Edit Each Line in Selection (⌃⌘A). En Sublime Text 2, usa Selection → Add Previous Line (⌃⇧↑) y Selection → 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 individuales

En los casos en que un conjunto de reglas incluye sólo una declaración, considera la eliminación de los saltos de línea para facilitar la lectura y que la edición sea más rápida. Cualquier conjunto de reglas con múltiples declaraciones debe ser dividido para separar líneas.

El factor clave es la detección de errores—v.g., un validador de CSS indicando que tienes un error de sintaxis en la línea 183. Con una sola declaración, no hay falla. Con múltiples declaraciones, líneas separadas es una necesidad para tu salud mental.

/* 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; }

Notación abreviada

Esfuérzate para limitar el uso de las declaraciones abreviadas para los casos en que debes establecer explícitamente todos los valores disponibles. Propiedades abreviadas sobreusadas comunmente incluyen:

Algunas veces no necesitamos establecer todos los valores que una propiedad abreviada representa. Por ejemplo, los encabezados HTML sólo establecen el margen superior e inferior, así que cuando sea necesario, sólo reemplaza estos valores. El uso excesivo de propiedades abreviadas a menudo conduce a código más descuidado con reemplazos innecesarios y efectos secundarios no intencionales.

La red de desarrolladores de Mozilla tiene un gran artículo sobre propiedades abreviadas para aquellos que no están famirializados con la notación y el 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;
}

Anidando en Less y Sass

Evita la anidación innecesaria. Sólo porque puedas anidar, no significa que debas hacerlo. Considera anidar solamente si debes extender el ámbito de los estilos al padre y hay multiples elementos para anidar.

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

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

Comentarios

El código es escrito y mantenido por personas. Asegúrate de que tu código es descriptivo, bien comentado, y accesible para otros. Los buenos comentarios de código transmiten contexto o propósito. No te limites a reiterar un nombre de componente o clase.

Asegúrate de escribir oraciones completas o comentarios más grandes y frases concisas para las notas generales.

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

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

Nombres de clase

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

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

Selectores

Lectura adicional:

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

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

Organización

/*
 * 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 { ... }

Ajustes del editor

Configura tu editor con los siguientes ajustes para evitar las comunes inconsistencias de código y diffs sucios:

Considera documentar y aplicar estos ajustes al archivo .editorconfig de tu proyecto. Por ejemplo, echa un vistazo al que hay en Bootstrap. Aprende más acerca del EditorConfig.