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.
</li> ou </body>).<!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>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>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>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">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>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.
<!-- CSS externe-->
<link rel="stylesheet" href="code-guide.css">
<!-- CSS dans le document -->
<style>
/* ... */
</style>
<!-- JavaScript -->
<script src="code-guide.js"></script>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.
Les attributs HTML devraient apparaitre dans cet ordre, afin de faciliter la lecture du code.
classid, namedata-*src, for, type, href, valuetitle, altrole, aria-*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="...">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>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="...">Écrire du balisage dans un fichier Javascript rend son contenu plus difficile à trouver, plus difficile à éditer et moins performant. Évitez autant que possible.
: pour chaque déclaration.box-shadow).rgb(), rgba(), hsl(), hsla(), ou rect(). Cela permet de différencier les multiples valeurs de couleurs (virgule, sans espace) des multiples valeurs de propriétés (virgule, avec espace)..5 plutôt que 0.5 et -.5px plutôt que -0.5px).#fff. Les lettres minuscules sont bien plus facile à repérer lorsqu'on scanne visuellement un document car elles ont des formes plus uniques.#fff plutôt que #ffffff.input[type="text"]. Ils sont optionnels dans certains cas, mais c'est une bonne pratique pour la cohérence.margin: 0; plutôt que margin: 0px;.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;
}Les déclarations de propriétés similaires devraient être regroupées ensemble selon cet ordre :
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;
}@importComparé à 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 :
<link>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>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 { ... }
}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);
}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; }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 :
paddingmarginfontbackgroundborderborder-radiusBien 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;
}É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 { … }
}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;
}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 {
...
}.btn et .btn-danger)..btn est utile pour un button, mais .s ne veut rien dire..js-* pour indiquer un comportement (par opposition à un style), mais laissez ces classes en dehors de votre CSS.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 { ... }[class^="..."]) sur des éléments apparaissant souvent dans la page. La performance du navigateur est impactée par ces 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 { ... }/*
* 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 { ... }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.