Commentaire CSS et HTML : Syntaxe, Bonnes Pratiques et Exemples

Pourquoi commenter son code CSS et HTML ?

Les commentaires en CSS et HTML sont essentiels pour la maintenabilité de vos projets web. Un code bien commenté facilite la collaboration en équipe, aide à comprendre les décisions techniques prises il y a des mois, et accélère considérablement le débogage.

Chez Tourak Digital, nous imposons des standards de documentation du code dans tous nos projets. Voici notre guide complet sur les commentaires CSS et HTML.

Syntaxe des commentaires en HTML

Le commentaire HTML standard

En HTML, les commentaires utilisent la syntaxe suivante :

Cas d'utilisation des commentaires HTML

Commentaires conditionnels HTML (legacy)

Historiquement utilisés pour cibler Internet Explorer, ces commentaires sont obsolètes en 2026 mais vous pourriez les rencontrer dans du code legacy :

Syntaxe des commentaires en CSS

Commentaire bloc CSS (/* */)

Le CSS n'accepte qu'un seul type de commentaire natif, le commentaire bloc :

/* Ceci est un commentaire CSS sur une ligne */

/*
 * Ceci est un commentaire CSS
 * sur plusieurs lignes
 * avec des astérisques décoratifs
 */

.button {
    background-color: #3498db; /* Bleu principal de la marque */
    padding: 12px 24px; /* Espacement confortable au clic */
    border-radius: 6px; /* Coins arrondis subtils */
}

Commentaire ligne en préprocesseurs (//)

Si vous utilisez Sass, Less ou PostCSS, vous pouvez utiliser les commentaires sur une ligne :

// Ce commentaire ne sera PAS compilé dans le CSS final
// Utile pour les notes de développement

/* Ce commentaire SERA conservé dans le CSS compilé */

$primary-color: #3498db; // Bleu principal
$font-size-base: 16px;   // Taille de police de base

.card {
    // Layout
    display: flex;
    flex-direction: column;

    // Espacement
    padding: 1.5rem;
    margin-bottom: 2rem;

    // Visuel
    background: white;
    border-radius: 8px;
    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
}

Systèmes de documentation CSS professionnels

La méthode des sections avec bannières

/* ==========================================================================
   COMPOSANTS - BOUTONS
   ========================================================================== */

/*
 * Bouton primaire
 * Utilisé pour les actions principales (CTA, soumission de formulaire)
 * Variations : .btn--large, .btn--small, .btn--outline
 */
.btn-primary {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    padding: 0.75rem 1.5rem;
    font-size: 1rem;
    font-weight: 600;
    color: white;
    background-color: var(--color-primary);
    border: 2px solid transparent;
    border-radius: 0.5rem;
    cursor: pointer;
    transition: all 0.2s ease;
}

/* État hover - légèrement plus foncé */
.btn-primary:hover {
    background-color: var(--color-primary-dark);
    transform: translateY(-1px);
}

/* ==========================================================================
   COMPOSANTS - CARTES
   ========================================================================== */

/*
 * Carte de base
 * Conteneur polyvalent utilisé dans les grilles
 * Dépendances : variables.css (--shadow-sm, --radius-md)
 */
.card {
    background: white;
    border-radius: var(--radius-md);
    box-shadow: var(--shadow-sm);
    overflow: hidden;
}

Le format CSSDOC

/**
 * @section Navigation
 * @description Styles pour la barre de navigation principale
 * @author Tourak Digital
 * @version 2.1
 * @since 1.0
 *
 * @example
 *   
 */
.main-nav {
    position: sticky;
    top: 0;
    z-index: 1000;
    background: white;
    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

Annotations de commentaires standardisées

Commentaires et performances

Les commentaires impactent-ils les performances de votre site ?

• En développement : aucun impact, gardez tous vos commentaires.
• En production : les commentaires augmentent la taille des fichiers. Utilisez un minifieur.
• Minification automatique : des outils comme cssnano, UglifyCSS ou les bundlers (Webpack, Vite) suppriment automatiquement les commentaires en production.
• Gzip/Brotli : la compression du serveur réduit considérablement l'impact des commentaires restants.

/* Configuration Vite pour minifier le CSS */
// vite.config.js
export default {
    build: {
        cssMinify: true, // Supprime les commentaires en prod
    }
}

/* PostCSS avec cssnano */
// postcss.config.js
module.exports = {
    plugins: [
        require('cssnano')({
            preset: ['default', {
                discardComments: { removeAll: true }
            }]
        })
    ]
}

Les erreurs fréquentes avec les commentaires

• Commentaires imbriqués en CSS : le CSS ne supporte pas les commentaires imbriqués. /* outer /* inner */ */ causera une erreur.
• Commentaires // en CSS natif : // n'est pas valide en CSS pur, uniquement dans les préprocesseurs.
• Oublier de fermer un commentaire : un /* sans */ commentera tout le reste du fichier.
• Commentaires HTML dans le CSS : ne fonctionne pas dans les fichiers CSS.
• Informations sensibles : ne mettez jamais de mots de passe, clés API ou données personnelles dans les commentaires.

Bonnes pratiques de commentaires chez Tourak Digital

• Commentez le pourquoi, pas le quoi (le code devrait être auto-descriptif)
• Utilisez des bannières de section pour structurer les gros fichiers CSS
• Adoptez un système d'annotations cohérent (TODO, FIXME, HACK)
• Documentez les valeurs magiques (z-index: 9999; /* Au-dessus du modal */)
• Expliquez les hacks de navigateurs et les solutions de contournement
• Mettez à jour les commentaires quand vous modifiez le code
• Supprimez le code commenté avant de merger (utilisez Git pour l'historique)

Conclusion

Les commentaires CSS et HTML sont un investissement dans la qualité de votre code. Un bon commentaire au bon endroit peut économiser des heures de débogage et faciliter la collaboration. Adoptez une convention de commentaires dans votre équipe et tenez-vous-y rigoureusement.

Besoin d'un site web avec un code propre et maintenable ? Tourak Digital livre du code professionnel documenté. Parlons de votre projet.