Quand je corrige les projets de mes étudiants en BTS SIO, je constate que le code SQL est souvent le grand oublié de la documentation. Des requêtes de 30 lignes sans la moindre explication, des jointures complexes dont personne ne se souvient du but trois mois plus tard. Les commentaires SQL sont pourtant l’un des outils les plus simples et les plus puissants pour rendre une base de données maintenable.

Dans ce guide, je vous montre comment utiliser chaque type de commentaire, les spécificités de chaque SGBD, et surtout les bonnes pratiques que j’enseigne à mes classes pour produire du code SQL professionnel.

Syntaxe des commentaires SQL : les deux formes essentielles

Le langage SQL, tel que défini par la norme ISO/IEC 9075, propose deux syntaxes de commentaires. Ces deux formes sont reconnues par la quasi-totalité des systèmes de gestion de bases de données relationnels (SGBDR) actuels.

La première syntaxe utilise deux tirets consécutifs (--) pour commenter une seule ligne. Tout ce qui suit ces deux tirets sur la même ligne est ignoré par le moteur SQL. La seconde syntaxe encadre le texte entre /* et */ pour créer un bloc de commentaire pouvant s’étendre sur plusieurs lignes.

Je recommande à mes étudiants de s’en tenir aux deux syntaxes normalisées pour garantir la portabilité du code. Le dièse (#) fonctionne sous MySQL, mais il rendra votre script incompatible si vous migrez un jour vers PostgreSQL ou SQL Server.

Commentaire SQL sur une seule ligne

Le commentaire sur une seule ligne est celui que vous utiliserez le plus souvent au quotidien. Il commence par -- (deux tirets suivis d’un espace par convention) et s’arrête automatiquement à la fin de la ligne.

En début de ligne

Placé en début de ligne, le commentaire sert à décrire l’instruction qui suit :

-- Récupération des clients actifs depuis plus d'un an
SELECT nom, prenom, date_inscription
FROM clients
WHERE actif = 1
  AND date_inscription < DATE_SUB(NOW(), INTERVAL 1 YEAR);

En fin de ligne (commentaire inline)

Placé en fin d’instruction, il apporte une précision ciblée :

SELECT
    c.nom,
    c.email,
    COUNT(co.id) AS nb_commandes  -- Nombre total, annulations incluses
FROM clients c
INNER JOIN commandes co ON co.client_id = c.id
GROUP BY c.id;

Pour désactiver temporairement du code

Un usage très courant en développement consiste à désactiver une clause sans la supprimer, pour tester une variante de requête :

SELECT *
FROM produits
WHERE categorie_id = 3
-- AND prix > 50  -- Filtre prix désactivé pour le debug
ORDER BY nom;

Cette technique est particulièrement utile quand vous travaillez sur des requêtes complexes impliquant des clauses WHERE combinées à des LEFT JOIN. Commenter une condition permet d’isoler rapidement la source d’un problème.

Comment commenter plusieurs lignes en SQL

Pour commenter un bloc entier de code SQL, on utilise la syntaxe /* ... */. Tout le texte compris entre l’ouverture /* et la fermeture */ est traité comme un commentaire, quelle que soit la quantité de lignes.

/*
  Requête de rapport mensuel
  Auteur : L. Moreau
  Dernière modification : 2026-06-10
  Objectif : extraire le chiffre d'affaires par catégorie
  pour le tableau de bord direction
*/
SELECT
    cat.libelle AS categorie,
    SUM(li.quantite * li.prix_unitaire) AS ca_total
FROM lignes_commande li
INNER JOIN produits p ON p.id = li.produit_id
INNER JOIN categories cat ON cat.id = p.categorie_id
GROUP BY cat.id
ORDER BY ca_total DESC;

Le commentaire bloc est également indispensable pour désactiver temporairement un ensemble d’instructions lors d’un débogage :

/*
INSERT INTO log_operations (operation, date_exec)
VALUES ('import_csv', NOW());
*/

-- Seule cette instruction sera exécutée
SELECT COUNT(*) FROM log_operations;

Un point important : dans la plupart des SGBD, les commentaires bloc ne peuvent pas être imbriqués. Si vous écrivez /* début /* milieu */ fin */, le moteur considérera que le commentaire se termine au premier */, et fin */ provoquera une erreur de syntaxe. L’exception notable est T-SQL (SQL Server), qui autorise l’imbrication.

Commentaires SQL selon les SGBD : MySQL, PostgreSQL, SQL Server, Oracle

Si la syntaxe de base est partagée, chaque SGBD possède ses particularités qu’il faut connaître pour éviter les pièges. Voici ce que j’ai observé en travaillant avec les quatre moteurs les plus utilisés.

MySQL

MySQL accepte les trois formes de commentaires : --, /* */ et #. La particularité de MySQL avec le commentaire -- est qu’il exige un espace après les deux tirets. Sans cet espace, l’instruction peut être mal interprétée.

MySQL propose aussi les commentaires conditionnels, une fonctionnalité exclusive :

SELECT /*! STRAIGHT_JOIN */ col1
FROM table1
INNER JOIN table2 ON table2.id = table1.fk_id;

Le code à l’intérieur de /*! ... */ est exécuté par MySQL mais traité comme un commentaire par les autres SGBD. C’est une technique astucieuse pour écrire des scripts portables contenant des optimisations spécifiques à MySQL. Vous pouvez même cibler une version minimale : /*!50700 ... */ n’exécutera le code que sur MySQL 5.7 et supérieur.

Pour approfondir d’autres aspects de MySQL, consultez la documentation officielle MySQL sur les commentaires.

PostgreSQL

PostgreSQL suit strictement la norme SQL et accepte -- et /* */. Fait intéressant, PostgreSQL autorise l’imbrication des commentaires bloc, contrairement à MySQL. Cela signifie que vous pouvez commenter un bloc qui contient déjà des commentaires :

/*
  Bloc externe commenté
  /* Ce commentaire interne est correctement géré */
  SELECT * FROM table_test;
*/

C’est un avantage notable lors du débogage de procédures stockées volumineuses.

Oracle

Oracle reconnaît les syntaxes -- et /* */. Une spécificité d’Oracle est la commande COMMENT ON qui permet d’attacher un commentaire directement à un objet de la base (table, colonne, vue) :

COMMENT ON TABLE employes IS 'Table principale des employés actifs et inactifs';
COMMENT ON COLUMN employes.matricule IS 'Identifiant RH unique, format MXXX';

Ces commentaires sont stockés dans le dictionnaire de données et consultables via les vues ALL_TAB_COMMENTS et ALL_COL_COMMENTS. C’est un outil précieux pour documenter le schéma directement au niveau du SGBD.

SQL Server

SQL Server, via T-SQL, mérite une section dédiée que je développe ci-dessous.

Comment commenter en T-SQL

Transact-SQL (T-SQL) est le dialecte SQL utilisé par Microsoft SQL Server et Azure SQL Database. En matière de commentaires, T-SQL offre quelques avantages notables par rapport aux autres dialectes.

Syntaxes disponibles

T-SQL reconnaît les deux syntaxes standard :

-- Commentaire sur une ligne en T-SQL

/*
  Commentaire bloc en T-SQL
  Peut s'étendre sur autant de lignes que nécessaire
*/

Imbrication des commentaires bloc

Comme PostgreSQL, T-SQL supporte l’imbrication des commentaires /* */. C’est extrêmement pratique quand vous devez désactiver un bloc de procédure stockée qui contient déjà ses propres commentaires :

/*
  Procédure temporairement désactivée pour maintenance
  /*
    Auteur : Équipe DBA
    Créée le : 2026-01-15
  */
  CREATE PROCEDURE sp_calcul_stats
  AS
  BEGIN
      SELECT COUNT(*) FROM ventes; -- Compte total
  END;
*/

Commentaires dans SSMS

Dans SQL Server Management Studio (SSMS), vous pouvez utiliser les raccourcis clavier pour commenter et décommenter rapidement du code : Ctrl+K, Ctrl+C pour commenter une sélection et Ctrl+K, Ctrl+U pour la décommenter. C’est un gain de productivité considérable quand on travaille sur de longues procédures stockées.

Si vous travaillez avec des requêtes utilisant des opérateurs UNION en SQL, les commentaires deviennent indispensables pour distinguer chaque partie de la requête combinée.

Bonnes pratiques pour commenter son code SQL

Écrire des commentaires ne suffit pas : encore faut-il qu’ils soient utiles. Après des années à relire du code SQL en entreprise et à corriger des travaux d’étudiants, voici les règles que j’applique systématiquement.

Commenter le pourquoi, pas le quoi

Le piège numéro un que je vois chez les débutants :

-- Mauvais : le commentaire répète le code
-- Sélectionne le nom du client
SELECT nom FROM clients;

-- Bon : le commentaire explique le contexte métier
-- Récupère uniquement le nom pour l'export RGPD (pas d'email ni téléphone)
SELECT nom FROM clients;

Le code SQL est déjà assez lisible en lui-même. Un SELECT nom FROM clients n’a pas besoin qu’on explique ce qu’il fait. En revanche, expliquer pourquoi on ne sélectionne que le nom apporte une vraie valeur ajoutée.

Documenter les requêtes complexes

Les situations qui méritent systématiquement un commentaire :

• Les sous-requêtes corrélées dont la logique n’est pas évidente
• Les jointures sur plus de 3 tables
• Les conditions WHERE avec des règles métier spécifiques
• Les fonctions d’agrégation avec des cas particuliers (NULL, doublons)
• Les CTE (WITH) enchaînées qui transforment les données étape par étape

Structurer les en-têtes de scripts

Pour chaque script SQL de plus de 20 lignes, j’ajoute un bloc d’en-tête normalisé :

/*
============================================
  Script : migration_v2_categories.sql
  Auteur : L. Moreau
  Date   : 2026-06-14
  But    : Restructurer la table catégories
           pour supporter la hiérarchie N niveaux
  Pré-requis : backup de la table catégories
============================================
*/

Éviter le sur-commentaire

Trop de commentaires est presque aussi problématique que pas assez. Un code noyé sous les commentaires devient difficile à lire, et les commentaires finissent par ne plus être maintenus. La règle que je donne à mes étudiants : si votre requête fait moins de 5 lignes et utilise des noms de colonnes explicites, un commentaire est probablement superflu.

Utiliser COMMENT ON quand c’est possible

Sur PostgreSQL et Oracle, privilégiez COMMENT ON pour documenter le schéma. Ces commentaires sont persistants, versionnés avec les migrations, et accessibles à tous les outils qui interrogent le dictionnaire de données.

COMMENT ON TABLE commandes IS 'Commandes validées uniquement. Les paniers abandonnés sont dans la table paniers_tmp.';
COMMENT ON COLUMN commandes.statut IS 'Valeurs possibles : en_attente, validee, expediee, livree, annulee';

Cette approche est complémentaire de la documentation de votre code applicatif. Si vous travaillez en PHP par exemple, combiner les commentaires SQL avec des enums PHP pour les valeurs de statut garantit une cohérence entre la base et le code.

Erreurs courantes avec les commentaires SQL

Certaines erreurs reviennent fréquemment, en particulier chez ceux qui débutent en SQL. Les identifier vous fera gagner un temps précieux en débogage.

Oublier l’espace après les deux tirets

En MySQL, --commentaire sans espace ne sera pas interprété comme un commentaire. La syntaxe correcte est -- commentaire avec un espace. PostgreSQL et SQL Server sont plus tolérants sur ce point, mais par sécurité, prenez l’habitude de toujours ajouter l’espace.

Imbriquer des commentaires bloc sur MySQL

/* Ceci est un commentaire
   /* imbriqué qui provoquera */
   une erreur sur MySQL */

MySQL ferme le commentaire au premier */ rencontré. Le texte une erreur sur MySQL */ sera interprété comme du SQL, ce qui déclenchera une erreur de syntaxe. Si vous devez commenter un bloc contenant des commentaires, utilisez plutôt des -- pour les commentaires internes.

Laisser des commentaires obsolètes

Un commentaire faux est pire que pas de commentaire du tout. Quand vous modifiez une requête, mettez à jour les commentaires associés. J’ai vu des bugs en production causés par des développeurs qui avaient suivi un commentaire obsolète au lieu de lire le code réellement exécuté.

Commenter au lieu de supprimer

Le code mort commenté est une mauvaise habitude héritée de l’époque sans gestionnaire de versions. Avec Git, supprimez le code inutile au lieu de le commenter. L’historique Git vous permettra toujours de le retrouver si nécessaire.

Les mêmes principes de documentation propre s’appliquent dans d’autres contextes, comme lorsque vous écrivez des templates Ansible avec Jinja2 où la clarté des commentaires est tout aussi critique.

Cas pratiques : commenter des requêtes réelles

Pour conclure la partie théorique, voici trois scénarios tirés de situations réelles que je rencontre en formation et en mission.

Cas 1 : requête de rapport avec CTE

-- Rapport : top 10 clients par CA sur les 12 derniers mois
-- Utilisé par le dashboard direction (rafraîchi chaque lundi)
WITH ventes_recentes AS (
    -- Filtre les commandes validées des 12 derniers mois
    SELECT client_id, montant_ttc
    FROM commandes
    WHERE statut = 'validee'
      AND date_commande >= DATE_SUB(CURDATE(), INTERVAL 12 MONTH)
),
ca_par_client AS (
    -- Agrège le CA par client
    SELECT client_id, SUM(montant_ttc) AS ca_total
    FROM ventes_recentes
    GROUP BY client_id
)
SELECT
    c.nom,
    c.email,
    cpc.ca_total
FROM ca_par_client cpc
INNER JOIN clients c ON c.id = cpc.client_id
ORDER BY cpc.ca_total DESC
LIMIT 10;

Cas 2 : script de migration avec vérifications

/*
  Migration #47 : ajout du champ 'code_postal' à la table adresses
  Ticket : JIRA-1234
  Rollback : ALTER TABLE adresses DROP COLUMN code_postal;
*/

-- Vérifier que la colonne n'existe pas déjà (idempotence)
SET @col_exists = (
    SELECT COUNT(*)
    FROM information_schema.COLUMNS
    WHERE TABLE_NAME = 'adresses'
      AND COLUMN_NAME = 'code_postal'
);

-- Ajout conditionnel de la colonne
/* Note : VARCHAR(10) pour supporter les codes postaux internationaux
   Le format français est sur 5 chiffres, mais certains clients
   ont des adresses de livraison à l'étranger */
ALTER TABLE adresses
ADD COLUMN code_postal VARCHAR(10) DEFAULT NULL;

Cas 3 : procédure stockée documentée

/*
  Procédure : sp_archiver_commandes
  Déplace les commandes de plus de 3 ans vers la table d'archive.
  Exécution : cron hebdomadaire, dimanche 03h00
  Attention : verrouille la table commandes pendant l'exécution.
  Ne pas lancer en journée sur l'environnement de production.
*/
DELIMITER //
CREATE PROCEDURE sp_archiver_commandes()
BEGIN
    DECLARE v_nb_archivees INT DEFAULT 0;

    -- Copie vers la table d'archive
    INSERT INTO commandes_archive
    SELECT * FROM commandes
    WHERE date_commande < DATE_SUB(NOW(), INTERVAL 3 YEAR);

    SET v_nb_archivees = ROW_COUNT(); -- Nombre de lignes déplacées

    -- Suppression des commandes archivées de la table principale
    DELETE FROM commandes
    WHERE date_commande < DATE_SUB(NOW(), INTERVAL 3 YEAR);

    -- Log de l'opération pour traçabilité
    INSERT INTO log_maintenance (operation, nb_lignes, date_exec)
    VALUES ('archivage_commandes', v_nb_archivees, NOW());
END //
DELIMITER ;

Ces exemples illustrent comment des commentaires bien placés transforment du code SQL technique en documentation vivante. Chaque commentaire apporte une information que le code seul ne transmet pas : le contexte métier, les précautions d’usage, ou la logique de rollback.

Pour aller plus loin dans l’écriture de requêtes robustes, je vous recommande de consulter mon guide sur SQL UNION et ses variantes qui complète parfaitement les notions abordées ici.

Lucie Moreau

Formatrice IT indépendante depuis 2016, ancienne étudiante BTS SIO SLAM. 6 ans d'expérience en entreprise.