Commentaire CSS : Un guide complet pour tout savoir

Lorsque l’on apprend à coder en CSS, on se concentre souvent sur les propriétés visuelles : les couleurs, les marges, les polices, ou les animations. Pourtant, un élément essentiel est souvent négligé par les débutants comme par certains développeurs expérimentés : le commentaire.

Le commentaire en CSS est un outil discret, mais incroyablement utile. Il ne modifie pas l’apparence d’un site, il ne change pas la mise en page, et il n’ajoute aucun effet visuel. Pourtant, il peut faire gagner un temps précieux, éviter de nombreuses erreurs et rendre un code beaucoup plus clair, surtout lorsqu’il doit être relu ou modifié plusieurs semaines ou mois plus tard.

Dans ce guide complet, nous allons explorer ce qu’est un commentaire CSS, à quoi il sert, comment l’utiliser efficacement, quand il est judicieux d’en ajouter, mais aussi quelles sont ses limites. Vous apprendrez également à vous en servir dans un contexte professionnel, pour structurer vos feuilles de style comme un véritable développeur web.

Qu’est-ce qu’un commentaire en CSS ?

Avant toute chose, il faut bien comprendre la nature d’un commentaire.
En CSS, un commentaire est une portion de texte qui n’est pas interprétée par le navigateur. Autrement dit, elle ne s’affiche pas sur le site, et elle n’a aucun effet sur le rendu visuel des pages web.

Le commentaire sert uniquement à vous (ou à d’autres développeurs) pour comprendre ce que fait votre code.

La syntaxe d’un commentaire CSS

La syntaxe d’un commentaire en CSS est très simple.
On l’écrit entre les symboles /* et */.

Par exemple :

/* Ceci est un commentaire en CSS */
body {
  background-color: #f5f5f5;
}

Tout ce qui se trouve entre ces deux symboles est ignoré par le navigateur.
Vous pouvez écrire un commentaire sur une seule ligne ou sur plusieurs lignes :

/* 
  Ce bloc concerne la mise en page principale du site.
  On y définit les marges et la largeur du contenu.
*/
.container {
  max-width: 1200px;
  margin: 0 auto;
}

Ce format est universel : il fonctionne dans tous les navigateurs et sur toutes les versions de CSS, du plus ancien au plus moderne.

À quoi servent les commentaires en CSS ?

Les commentaires ne servent pas seulement à « décorer » le code. Ils remplissent plusieurs fonctions précises et très utiles dans le développement quotidien.

Expliquer le rôle d’un bloc de code

La première fonction d’un commentaire CSS est d’expliquer l’intention derrière le code.

Imaginez que vous repreniez un projet au bout de six mois. Vous tombez sur une règle complexe avec plusieurs propriétés. Sans commentaire, vous risquez d’oublier pourquoi vous avez choisi ces valeurs, ou à quoi correspond une classe.

Exemple :

/* 
  Section : Page d'accueil
  Objectif : centrer le contenu principal et ajouter un effet d'ombre.
*/
.home-section {
  margin: 0 auto;
  box-shadow: 0 2px 8px rgba(0,0,0,0.2);
}

En ajoutant ces quelques lignes explicatives, vous facilitez grandement la compréhension du code, aussi bien pour vous que pour toute autre personne qui viendrait travailler sur le même projet.

Organiser et structurer les feuilles de style

Lorsque votre fichier CSS devient long (ce qui est souvent le cas dans les vrais projets), les commentaires permettent de créer une structure logique.
Ils servent de repères visuels, comme des titres de chapitre dans un livre.

Par exemple :

/* =====================
   1. Styles généraux
   ===================== */

/* =====================
   2. En-tête du site
   ===================== */

/* =====================
   3. Pied de page
   ===================== */

Grâce à ces séparateurs, vous pouvez retrouver rapidement la section que vous cherchez, sans avoir à faire défiler tout le fichier. Cette habitude est très utilisée dans les projets professionnels où les feuilles de style dépassent parfois plusieurs milliers de lignes.

Désactiver temporairement du code (commenter du CSS)

Les commentaires peuvent également servir à désactiver une portion de code sans la supprimer. C’est très utile pour tester une autre mise en forme, faire des essais, ou déboguer un problème d’affichage.

Exemple :

/*
.header {
  background-color: red;
}
*/

Dans cet exemple, la règle .header ne sera pas lue par le navigateur tant qu’elle reste entourée par les balises de commentaire.
Cela permet d’expérimenter sans perdre le code original.

Les avantages des commentaires en CSS

Utiliser les commentaires présente de nombreux avantages, aussi bien en apprentissage qu’en développement professionnel.

Améliorer la lisibilité du code

Un code commenté est un code facile à relire et à comprendre.
Cela peut sembler évident, mais c’est un atout considérable lorsqu’un projet évolue ou lorsqu’il est repris par une autre personne.

Un développeur qui lit votre fichier CSS comprendra rapidement vos intentions, sans devoir deviner le rôle de chaque classe ou propriété. Cela facilite la collaboration et accélère le travail d’équipe.

Faciliter la maintenance à long terme

Les commentaires vous permettent de garder une trace de vos choix techniques.
Ils peuvent contenir des explications, des justifications ou même des rappels sur des points à corriger plus tard.

Par exemple :

/* À améliorer : trouver une couleur plus accessible pour ce texte */
p.warning {
  color: #f00;
}

Ce type de note est extrêmement utile lorsqu’on doit effectuer une refonte graphique ou corriger un bug.

Gagner du temps sur les grands projets

Lorsqu’un fichier CSS atteint plusieurs centaines de lignes, il devient difficile de s’y repérer. Les commentaires agissent alors comme des signets internes.
Ils permettent de naviguer rapidement d’une section à l’autre, surtout lorsqu’ils suivent une numérotation logique (1. Général, 2. Header, 3. Navigation, etc.).

Cette méthode, très utilisée dans les frameworks CSS faits maison, évite la confusion et améliore la productivité.

Favoriser le travail en équipe

Dans un projet collectif, il est rare qu’une seule personne écrive tout le CSS. Les commentaires deviennent alors un moyen de communication entre développeurs.
Ils permettent d’indiquer ce qu’une classe fait, pourquoi elle a été écrite ainsi, ou encore d’avertir qu’une règle dépend d’un comportement particulier du site.

Exemple :

/* Attention : cette règle dépend du JavaScript du menu mobile */
.menu-open {
  transform: translateX(0);
}

Ces petits messages internes évitent les mauvaises surprises et les erreurs d’interprétation.

Comment bien utiliser les commentaires CSS

Il ne suffit pas de commenter, encore faut-il le faire correctement.
Un excès de commentaires peut nuire à la clarté du code, tandis qu’un manque d’explications peut le rendre difficile à maintenir.

Trouver le bon équilibre

L’idéal est de commenter ce qui n’est pas évident.
Si une ligne parle d’elle-même, inutile de la commenter. Mais si une règle est un peu technique, ou si elle résout un problème spécifique, un court commentaire sera très utile.

Par exemple :

/* Correction du bug d’affichage sous Safari */
.image {
  transform: translateZ(0);
}

Ce genre de note justifie une ligne de code qui pourrait sembler inutile à première vue.

Utiliser une mise en forme claire et homogène

Pour que vos commentaires soient lisibles, adoptez une mise en forme cohérente dans tout le fichier.
Utilisez les mêmes symboles, le même alignement et, si possible, une hiérarchie visuelle.

Certains développeurs utilisent par exemple des titres soulignés ou encadrés :

/* =======================================
   Section 2 : Barre de navigation
   ======================================= */

D’autres préfèrent un style plus sobre :

/* ----- Navigation ----- */

L’important n’est pas le style choisi, mais la cohérence à l’intérieur d’un même projet.

Les erreurs fréquentes avec les commentaires en CSS

Même si les commentaires semblent simples à utiliser, certaines erreurs reviennent souvent, surtout chez les débutants. En les connaissant, vous éviterez bien des frustrations et des bugs inattendus.

Oublier de fermer un commentaire

L’erreur la plus fréquente consiste à oublier de fermer le commentaire avec */.
Contrairement au HTML ou au JavaScript, le CSS ne tolère pas les erreurs de syntaxe dans les commentaires.
Si vous oubliez de fermer un commentaire, tout le code qui suit sera ignoré par le navigateur.

Exemple d’erreur :

/* Ceci est un commentaire non fermé
body {
  background-color: blue;
}

Dans cet exemple, la propriété background-color ne sera jamais appliquée, car le navigateur considère que tout le reste du fichier fait partie du commentaire.
C’est une erreur silencieuse, difficile à détecter, surtout dans un long fichier CSS.

Pour éviter cela, habituez-vous à fermer immédiatement votre commentaire dès que vous ouvrez le symbole /*, même avant d’écrire le texte :

/*  */

Ensuite, revenez entre les deux symboles pour rédiger votre note.

Commenter du code mal placé

Une autre erreur courante consiste à commenter une partie d’une règle CSS, ce qui peut casser la structure.

Exemple :

p {
  color: red; /* Ceci est un test
  font-size: 16px;
}

Ici, le commentaire n’est pas fermé avant la fin de la règle. Résultat : le navigateur ne lit plus rien après le color.
Cette erreur est souvent difficile à repérer à l’œil nu.
Là encore, un bon réflexe consiste à placer les commentaires en dehors des blocs de code, ou sur une ligne distincte.

/* Style principal du paragraphe */
p {
  color: red;
  font-size: 16px;
}

Multiplier les commentaires inutiles

Un autre piège est de vouloir tout commenter.
Un excès de commentaires peut rapidement alourdir votre fichier et rendre la lecture plus confuse.

Par exemple :

/* Sélecteur du body */
body {
  /* Couleur de fond */
  background-color: white;
  /* Couleur du texte */
  color: black;
  /* Taille de police */
  font-size: 16px;
}

Ici, les commentaires ne servent à rien : chaque propriété est explicite par elle-même.
Le but du commentaire est d’expliquer le pourquoi, pas le quoi.

Un bon commentaire serait plutôt :

/* Palette neutre choisie pour faciliter la lecture sur fond clair */
body {
  background-color: white;
  color: black;
  font-size: 16px;
}

Les limites des commentaires CSS

Même s’ils sont pratiques, les commentaires CSS ont leurs limites techniques et logiques.
Il est important de les connaître pour éviter de mauvaises utilisations.

Les commentaires ne sont pas visibles dans le navigateur

Contrairement à certains langages comme le HTML, les commentaires CSS ne peuvent pas être inspectés directement depuis la console ou les outils de développement du navigateur.
Ils sont supprimés dès que le navigateur interprète le fichier CSS.

Des formations informatique pour tous !

Débutant ou curieux ? Apprenez le développement web, le référencement, le webmarketing, la bureautique, à maîtriser vos appareils Apple et bien plus encore…

Formateur indépendant, professionnel du web depuis 2006, je vous accompagne pas à pas et en cours particulier, que vous soyez débutant ou que vous souhaitiez progresser. En visio, à votre rythme, et toujours avec pédagogie.

Découvrez mes formations Qui suis-je ?

Cela signifie qu’un utilisateur ne peut pas voir vos commentaires, sauf s’il ouvre directement le fichier source via un lien public.

Les commentaires sont conservés dans les fichiers non compressés

Dans les fichiers CSS non minifiés (c’est-à-dire en version lisible), vos commentaires restent visibles.
Mais dès que vous minifiez le code pour optimiser les performances d’un site, les commentaires sont en général automatiquement supprimés par les outils de build comme Webpack, Gulp ou PostCSS.

Cela permet de réduire le poids du fichier final, mais vous perdez vos annotations.

La bonne pratique consiste donc à conserver les commentaires uniquement dans la version de développement, et à les supprimer ou compresser lors de la mise en production.

Les commentaires ne doivent pas contenir de code HTML

Certains débutants essayent parfois de commenter du code HTML à l’intérieur d’un fichier CSS, ce qui provoque des erreurs.

Exemple :

/* <div class="header"></div> */

Cette pratique n’a aucun sens dans une feuille de style.
Si vous avez besoin de documenter une partie du HTML, faites-le dans le fichier .html lui-même, pas dans le CSS.

Les commentaires n’exécutent pas de code

Il peut être tentant de laisser des notes comme /* à faire : changer la couleur */, mais il faut bien garder à l’esprit que ces commentaires ne sont jamais interprétés par un moteur CSS.
Ils ne peuvent pas exécuter de fonction, ni influencer le comportement du code.

Ils sont uniquement là pour la documentation humaine.

Les bonnes pratiques pour des commentaires efficaces

Pour que vos commentaires soient vraiment utiles, certaines habitudes simples peuvent transformer vos fichiers CSS en un véritable guide technique.

Utiliser une structure hiérarchique

Une méthode très répandue consiste à structurer vos fichiers CSS à l’aide de titres, sous-titres et séparateurs.
Cela rend le document plus facile à parcourir et à maintenir.

Exemple :

/* ===================================================
   1. Styles globaux
   =================================================== */

/* 1.1 Couleurs et polices */
body {
  color: #333;
  font-family: Arial, sans-serif;
}

/* 1.2 Liens */
a {
  color: #0056b3;
}

/* ===================================================
   2. En-tête du site
   =================================================== */

Cette approche hiérarchique est particulièrement utile lorsque plusieurs développeurs travaillent ensemble. Elle permet de repérer rapidement chaque section et d’ajouter des sous-parties claires.

Standardiser le format des commentaires dans l’équipe

Si vous travaillez en équipe, il est essentiel d’adopter une convention commune.
Par exemple, décider que tous les titres de section seront écrits en majuscules, avec un encadrement, ou qu’ils suivront une numérotation.

Cela crée une cohérence qui facilite la lecture du code par tous.
Dans certains projets, on documente même ces règles dans un fichier appelé styleguide.

Documenter les choix techniques

Un bon commentaire explique les raisons d’un choix technique.
Pourquoi avez-vous utilisé flexbox plutôt que grid ?
Pourquoi cette couleur précise ? Pourquoi ce z-index inhabituel ?

Exemple :

/* Utilisation de flexbox pour gérer l'alignement vertical
   (incompatible avec la solution grid sur Safari iOS 12) */
.header {
  display: flex;
  align-items: center;
}

Ce genre d’explication permet à vos collègues — ou à vous-même, dans quelques mois — de comprendre immédiatement les contraintes du projet.

Ajouter des marqueurs pour retrouver facilement une section

Une astuce pratique consiste à insérer des marqueurs dans vos commentaires, que vous pourrez rechercher rapidement avec votre éditeur de code.

Par exemple :

/* TODO : ajouter un effet de survol sur le bouton */

ou

/* FIX : corriger le bug d’alignement sur mobile */

Ces balises sont reconnues par la plupart des éditeurs modernes (comme VS Code), qui les affichent dans une liste de tâches. Vous pouvez ainsi suivre vos corrections directement depuis votre environnement de travail.

Les commentaires dans les préprocesseurs CSS (SASS, LESS, etc.)

Si vous utilisez un préprocesseur CSS comme SASS, SCSS ou LESS, sachez que le comportement des commentaires peut légèrement changer.

Les deux types de commentaires en SASS/SCSS

Dans ces langages, il existe deux formes de commentaires :

• /* ... */ : commentaire classique, conservé dans le fichier CSS final.
• // ... : commentaire de développeur, supprimé lors de la compilation.

Exemple :

/* Ce commentaire sera présent dans le CSS final */
body {
  background: white;
}

// Ce commentaire sera supprimé à la compilation
h1 {
  color: black;
}

Cela permet de séparer les notes destinées à la documentation de celles réservées au développement interne.

Les commentaires de documentation automatique

Certains outils comme StyleDocco ou KSS (Knyle Style Sheets) exploitent les commentaires CSS pour générer automatiquement une documentation technique du design d’un site.
Ces commentaires suivent une syntaxe spéciale qui permet de décrire chaque composant, ses classes, ses variables, etc.

Par exemple :

/*
Button
-------------------
Bouton principal du site.

Markup:
<button class="btn btn-primary">Valider</button>
*/

Grâce à ce type de commentaire enrichi, un outil externe peut produire une documentation visuelle du styleguide du projet, utile pour les équipes design et développement.

Les usages avancés des commentaires en CSS

Au-delà des usages classiques que nous avons vus, il existe des méthodes plus sophistiquées pour tirer le maximum des commentaires dans vos projets CSS, surtout lorsque vous travaillez sur des sites complexes ou en équipe.

Documenter les dépendances et contraintes

Dans un projet professionnel, certaines règles CSS dépendent de scripts JavaScript ou de comportements spécifiques d’un composant.
Ajouter un commentaire précis permet de prévenir toute mauvaise manipulation.

Exemple :

/* Dépendance JS : le menu mobile utilise ce style pour l'animation de translation */
.menu-mobile.open {
  transform: translateX(0);
}

Grâce à ce commentaire, un autre développeur saura immédiatement que modifier ce bloc peut casser l’interaction du menu.

Créer des templates de documentation internes

Certaines équipes utilisent les commentaires pour créer une documentation interne directement dans le fichier CSS.
Chaque composant ou section peut avoir un modèle structuré, incluant : le nom de la section, son rôle, ses variations et ses contraintes.

Exemple :

/*
Composant : Card
Fonction : Encadrer un contenu visuel avec titre et description
Variantes : .card-primary, .card-secondary
Contraintes : max-width 400px, padding standard
*/
.card {
  border: 1px solid #ddd;
  padding: 16px;
  border-radius: 8px;
}

Ce type de commentaire facilite la maintenance, surtout sur les projets utilisant des design systems ou des frameworks internes.

Utiliser les commentaires pour les tests et expérimentations

Quand vous essayez plusieurs approches pour un composant, les commentaires permettent de garder des versions alternatives sans les supprimer définitivement.

Exemple :

/*
.button {
  background-color: red;
  color: white;
}
*/

.button {
  background-color: #0056b3;
  color: white;
}

Ici, vous pouvez revenir à l’ancienne version rapidement si nécessaire.

Les commentaires et le SEO des fichiers CSS

Même si les commentaires CSS ne sont pas interprétés par les moteurs de recherche, un code bien commenté facilite la maintenance du site, ce qui peut indirectement améliorer le SEO.
Un fichier CSS clair et organisé permet d’apporter plus facilement des améliorations sur les performances et la vitesse de chargement, deux facteurs pris en compte par Google.

Quand utiliser les commentaires CSS

Savoir quand commenter est tout aussi important que savoir comment le faire.

1. Pour expliquer des choix complexes ou techniques : toute règle qui ne serait pas évidente pour un autre développeur mérite un commentaire.
2. Pour structurer le fichier : utilisez des titres et séparateurs pour guider la lecture.
3. Pour signaler des bugs ou points à améliorer : les balises TODO ou FIXME sont très utiles.
4. Pour tester du code temporairement : désactivez des blocs sans les supprimer.
5. Pour documenter des dépendances externes : signalez si une règle CSS est liée à un script ou à une interaction particulière.

Le mot d’ordre est : commenter avec intention et parcimonie. Trop de commentaires inutiles alourdissent le fichier et perdent leur utilité.

Astuces professionnelles pour des commentaires CSS efficaces

Voici quelques techniques avancées que les développeurs professionnels utilisent pour rendre leurs commentaires encore plus utiles :

• Hiérarchiser les sections par numéro : numéroter les sections et sous-sections facilite la navigation dans de grands fichiers.
• Utiliser un style visuel : encadrer les titres de sections ou utiliser des séparateurs visuels pour repérer rapidement une partie du fichier.
• Ajouter des marqueurs de suivi : TODO, FIXME, NOTE, HACK permettent de filtrer et de retrouver rapidement des parties du code.
• Documenter la compatibilité navigateur : signalez si une règle ne fonctionne que sur certains navigateurs ou versions.
• Séparer les commentaires de développement et de production : dans les projets minifiés, supprimez les commentaires internes pour réduire la taille des fichiers.

Supprimer les commentaires pour le mode production

Pour optimiser vos fichiers CSS en vue d’une mise en production, il est essentiel de supprimer les commentaires qui ne sont pas nécessaires. Ces commentaires, bien utiles lors du développement pour documenter le code et expliquer certaines sections, n’apportent aucune valeur au rendu final pour l’utilisateur et alourdissent inutilement le fichier CSS. Pour les supprimer, vous pouvez utiliser plusieurs approches.

La première consiste à automatiser la tâche grâce à des outils de build ou des préprocesseurs CSS. Par exemple, si vous utilisez un préprocesseur comme Sass ou Less, vous pouvez configurer la compilation pour produire un fichier CSS compressé, appelé souvent « minifié », où tous les commentaires sont supprimés sauf ceux que vous souhaitez conserver explicitement. Cela se fait généralement en utilisant des options telles que --style=compressed pour Sass.

Si vous travaillez directement avec du CSS pur, vous pouvez utiliser des outils de minification tels que PostCSS avec des plugins dédiés, ou des services en ligne qui prennent votre fichier CSS et génèrent une version optimisée sans les commentaires. Ces outils parcourent votre code, retirent tout ce qui est inclus entre /* et */ et produisent un fichier plus léger, tout en conservant l’intégrité du style.

Vous pouvez également intégrer cette étape dans votre processus de déploiement. Chaque fois que vous préparez votre projet pour la production, vous lancez un script qui minifie vos fichiers CSS. Cela garantit que vos utilisateurs bénéficient de pages plus rapides à charger, tout en conservant votre code original et commenté dans votre environnement de développement.

L’art de commenter son CSS

Les commentaires CSS ne sont pas un simple ajout décoratif : ils constituent un véritable outil de communication et d’organisation dans vos fichiers de style.

Bien utilisés, ils vous permettent de :

• clarifier vos intentions,
• structurer vos feuilles de style,
• faciliter la maintenance et la collaboration,
• documenter des choix techniques ou des contraintes spécifiques.

Mal utilisés ou excessifs, ils peuvent alourdir le code et nuire à la lisibilité. L’objectif est donc de commenter avec discernement, en expliquant le pourquoi plutôt que le quoi, et en créant une structure claire et cohérente.

Dans un projet moderne, notamment avec des préprocesseurs CSS ou des design systems, les commentaires prennent une dimension supplémentaire : ils servent de documentation intégrée, de guide pour l’équipe, et parfois même de base pour générer automatiquement des guides visuels ou techniques.

Le commentaire est le pont entre le code et la compréhension humaine. Sans lui, même le meilleur code peut devenir illisible avec le temps. Avec lui, votre CSS devient non seulement fonctionnel, mais également clair, maintenable et professionnel.

Apprendre à commenter correctement votre CSS, c’est apprendre à écrire du code compréhensible et durable, un atout essentiel pour tout développeur web sérieux.

Alban

Fondateur de l’agence Créa-troyes.
Intervenant en Freelance.
Contactez-moi

crea-troyes.fr