Guide de Code par @mdo

Standards pour des fichiers HTML et CSS flexibles, durables et maintenables.

Table des matières

HTML

CSS

Règle d'or

Définissez vos propres règles, ou suivez celle-ci, mais forcez-vous à les suivre tout le temps. Les petites comme les grandes infractions aux règles doivent être corrigées. Pour tout ajout ou contribution à ce Guide de Code, merci d'ouvrir un ticket sur GitHub.

Toutes les lignes de code doivent sembler avoir été écrites par la même personne, quelque soit le nombre de contributeurs.

HTML

Syntaxe

<!DOCTYPE html>
<html>
  <head>
    <title>Titre de la page</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Société">
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>

Doctype HTML5

Forcez le mode standard et donc un affichage plus cohérent dans tous les navigateurs possibles avec ce simple doctype au début de chaque page HTML.

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

Attributs de langue

D'après la spec HTML5:

Les auteurs sont encouragés à spécifier un attribut de langue sur l'élément racine html, afin de donner une langue au document. Ceci aide les outils de synthèse vocale à déterminer la prononciation à utiliser, les outils de traductions à choisir les règles à utiliser, etc.

Vous pouvez en savoir plus sur l'attribut lang en lisant la spec.

Rendez-vous sur Sitepoint pour une liste des codes de langue.

<html lang="fr-fr">
  <!-- ... -->
</html>

Mode de compatibilité IE

Internet Explorer supporte l'utilisation d'une balise de compatibilité <meta> pour spécifier sous quelle version de IE la page devrait être rendue. Sauf cas exceptionnel, il est préférable de dire à IE d'utiliser le dernier mode de rendu supporté avec le edge mode.

Pour plus d'informations, vous pouvez lire cet extraordinaire article sur Stack Overflow.

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

Codage des caractères

Assurez vous rapidement et facilement d'un bon rendu de votre contenu en déclarant de manière explicite le codage des caractères. En faisant ainsi, vous pouvez éviter d'utiliser des entités HTML, pour peu que leur encoding corresponde à celui du document (généralement UTF-8)

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

Inclusions CSS et Javascript

Selon la spec HTML, il n'est pas nécessaire de spécifier un type lorsque vous incluez des fichiers CSS ou Javascript puisque text/css et text/javascript sont leurs valeurs par défaut respectives.

Liens vers la spec HTML5

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

<!-- CSS dans le document -->
<style>
  /* ... */
</style>

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

Pragmatisme plutôt que pureté

Tendez à maintenir les standards et la sémantique HTML, mais pas au dépends du pragmatisme. Autant que possible, cherchez à utiliser le moins de balisage possible, avec le moins d'imbrication possible.

Ordre des attributs

Les attributs HTML devraient apparaitre dans cet ordre, afin de faciliter la lecture du code.

Les classes sont de très bon composants réutilisables, ils doivent donc apparaitre en premier. Les Ids sont plus spécifiques et doivent donc être utilisés avec parcimonie (e.g. pour des liens internes à la page), ils viennent donc en seconde position.

<a class="..." id="..." data-toggle="modal" href="#">
  Lien d'exemple
</a>

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

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

Attributs booléens

Un attribut booléen est un attribut qui ne nécessite pas de valeur. Il était nécessaire d'en ajouter un en XHTML, mais HTML5 n'a pas ce pré-requis.

Pour plus d'informations, consultez la section WhatWG sur les attributs booléens:

La présence d'un attribut booléen sur un élément représente la valeur vraie, et l'absence de l'attribut représente la valeur faux.

Si vous devez inclure la valeur de l'attribut, mais que vous n'en avez pas besoin, suivez cette bonne pratique du WhatWG :

Si l'attribut est présent, sa valeur doit soit être une chaine vide ou [...] le nom canonique de l'attribut, sans espace ni devant, ni derrière.

En clair, n'ajoutez pas de valeur.

<input type="text" disabled>

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

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

Réduire le balisage

Autant que possible, évitez les éléments parents inutiles quand vous écrivez du HTML. Bien souvent, cela nécessite plusieurs passes et du refactoring, mais cela produit moins de HTML. Prenez l'exemple suivant :

<!-- Pas si bon -->
<span class="avatar">
  <img src="...">
</span>

<!-- Bien mieux -->
<img class="avatar" src="...">

Balisage généré par Javascript

Écrire du balisage dans un fichier Javascript rend son contenu plus difficile à trouver, plus difficile à éditer et moins performant. Évitez autant que possible.

CSS

Syntaxe

Vous avez des questions sur les termes employés ici ? Référez-vous à la section sur la syntaxe de l'article sur les Cascading Style Sheets sur Wikipedia.

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

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

Ordre des déclarations

Les déclarations de propriétés similaires devraient être regroupées ensemble selon cet ordre :

  1. Positionnement
  2. Modèle de boîte
  3. Typographie
  4. Visuel

Le positionnement vient en premier car cela peut retirer un élément du flux normal du document et overrider les styles relatifs au modèle de boîte. Le modèle de boîte vient ensuite car il influe sur les dimensions et le placement de l'élément.

Tout le reste agissant à l'intérieur de l'élement ou sans impacter les deux sections précédentes, vient ensuite.

Pour une liste complète des propriétés et leur ordre, merci de vous référer à Recess.

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

  /* Modèle de boîte */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

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

  /* Visuel */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Divers */
  opacity: 1;
}

N'utilisez pas @import

Comparé à des <link>s, @import est plus lent, ajoute de nouvelles requêtes à la page et peut poser des problèmes imprévisibles. Évitez-les autant que possible et optez plutôt pour une approche alternative :

Pour plus d'informations, lisez cet article de Steve Souders.

<!-- Utilisation d'élements link -->
<link rel="stylesheet" href="core.css">

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

Emplacement des media queries

Placez les media queries le plus proche possible des règles qu'elles impactent. Ne les mettez pas toutes dans une feuille de style différente ou à la fin du document. En faisant ainsi, vous rendez la chose plus aisée pour les autres de ne pas les rater. Voici un exemple typique :

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

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

Propriétés prefixées

Lorsque vous utilisez des propriétés prefixées, indentez chaque propriété de telle manière que les déclarations s'alignent verticalement, de manière à rendre l'édition multi-ligne plus facile.

Sous TextMate, utilisez Text → Edit Each Line in Selection (⌃⌘A). Sous Sublime Text 2, utilisez Selection → Add Previous Line (⌃⇧↑) et Selection → Add Next Line (⌃⇧↓).

/* Propriétés prefixées */
.selector {
  -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
          box-shadow: 0 1px 2px rgba(0,0,0,.15);
}

Règles avec unique déclaration

Dans les cas où une règle ne contient qu'une seule déclaration, vous pouvez supprimer le saut de ligne pour faciliter la lecture et l'édition. Tout ensemble de règles avec plusieurs déclarations doit être découpé en plusieurs lignes.

L'élément important ici est la détection des erreurs — e.g., un validateur CSS qui vous indique que vous avez une erreur à la ligne 183. Avec une seule déclaration, vous ne pouvez pas vous tromper. Avec plusieurs déclarations, il est indispensable de séparer les lignes si vous tenez à votre santé mentale.

/* Déclarations uniques sur une seule ligne */
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

/* Déclarations multiples, une par ligne */
.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; }

Notations abrégées

Essayez de limiter l'utilisation de notations abrégées pour les cas où vous devez specifier explicitement toutes les valeurs. Les notations abrégées trop souvent abusées sont les suivantes :

Bien souvent vous n'avez pas besoin de spécifier toutes les valeurs qu'une notation abrégée vous propose. Par exemple, les entêtes de titre HTML ne définissent que des marges top et bottom, vous n'avez donc besoin que d'overrider ces valeurs. L'utilisation excessive des notations abrégées mène bien souvent à du code de mauvaise facture avec des overrides inutiles et des effets de bords non sollicités.

Le Mozilla Developer Network possède un très bon article sur les notations abrégées pour ceux qui ne sont pas familier avec leur syntaxe et comportement.

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

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

Imbrication avec Less et Sass

Évitez les imbrications inutiles. Ce n'est pas parce que vous pouvez faire de l'imbrication que vous devez le faire. N'imbriquez que si vous devez définir un scope parent pour un style et s'il y a plusieurs éléments à imbriquer.

Pour en savoir plus :

// Sans imbrication
.table > thead > tr > th {  }
.table > thead > tr > td {  }

// Avec imbrication
.table > thead > tr {
  > th {  }
  > td {  }
}

Opérateurs avec Less et Sass

Pour une meilleure lisibilité, englobez toutes les opérations mathématiques dans des parenthèses avec un simple espace entre les valeurs, les variables et les opérateurs.

// Bad example
.element {
  margin: 10px 0 @variable*2 10px;
}

// Good example
.element {
  margin: 10px 0 (@variable * 2) 10px;
}

Commentaires

Le code est écrit et maintenu par des humains. Assurez-vous que votre code est auto-portant, bien commenté et compréhensible par d'autres. Les bons commentaires apportent du contexte et de l'information. Ne répétez pas simplement le nom du composant ou de la classe.

Assurez-vous d'écrire des phrases complètes pour les longs commentaires et des phrases simples pour les notes d'ordre général.

/* Mauvais exemple */
/* Entête de modale */
.modal-header {
  ...
}

/* Bon exemple */
/* Encadrement de l'élément pour .modal-title et .modal-close */
.modal-header {
  ...
}

Nom des classes

Il est aussi utile d'appliquer la majorité de ces règles lorsque vous créez des noms de variable Less ou Sass.

/* Mauvais exemple */
.t { ... }
.red { ... }
.header { ... }

/* Bon exemple */
.tweet { ... }
.important { ... }
.tweet-header { ... }

Sélecteurs

Plus d'informations :

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

/* Bon exemple */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

Organisation

/*
 * Entête de section de composant
 */

.element { ... }


/*
 * Entête de section de composant
 *
 * Parfois, vous avez besoin d'ajouter plus de contexte pour le composant.
 */

.element { ... }

/* Sous-composant contextuel, ou modificateur */
.element-heading { ... }

Préférences de votre éditeur

Configurez votre éditeur avec la configuration suivante afin d'éviter les incohérences et les diffs sales :

Pensez à documenter et à appliquer ces préférences dans le fichier .editorconfig de votre projet. Par exemple, voici celui de Bootstrap. En savoir plus à propos de EditorConfig.