Accéder au contenu principal

Comment créer des commentaires en SQL

Passez en revue trois méthodes pour ajouter des commentaires en SQL : les commentaires sur une seule ligne, les commentaires sur plusieurs lignes et les commentaires en ligne en utilisant la syntaxe suivante : --, /* et */.
Actualisé 15 janv. 2025  · 5 min de lecture

SQL, qui signifie Structured Query Language, est un langage puissant permettant de gérer et de manipuler des bases de données relationnelles. Bien que les requêtes SQL puissent sembler explicites à première vue, l'ajout de commentaires dans les instructions SQL peut améliorer la lisibilité et la maintenabilité de votre code.

Dans ce tutoriel, nous verrons comment ajouter des commentaires en SQL pour rendre votre code plus simple et plus facile à lire.

La réponse rapide : Comment créer des commentaires en SQL

Il existe trois façons d'ajouter des commentaires à vos requêtes SQL :

  1. Commentaires sur une seule ligne : Les commentaires sur une seule ligne commencent par -- double tiret.

  2. Commentaires en ligne : Les commentaires en ligne commencent par -- après l'instruction SQL sur la même ligne.
  3. Commentaires multilignes ou Commentaires en bloc : Les commentaires multilignes commencent par /* et se terminent par */.

 -- Single line comment
SELECT * 
FROM TABLE

SELECT * 
FROM TABLE -- Inline comment

/* Multiline
comment */ 
SELECT * 
FROM TABLE  

Pourquoi les commentaires SQL sont-ils importants ?

Voici trois raisons essentielles pour lesquelles les commentaires SQL sont importants :

  • Clarifier l'objectif du code : Les commentaires expliquent l'objectif et la logique du code, ce qui facilite sa compréhension par les autres et par vous-même lorsque vous le relirez plus tard.
  • Améliorer le travail d'équipe : Les commentaires facilitent le travail d'équipe en documentant le code pour les autres développeurs et en les aidant à comprendre votre travail.
  • Aide au débogage et à l'optimisation : Les commentaires simplifient le processus de débogage et d'optimisation du code au fil du temps, ce qui facilite l'identification et la correction des problèmes.

Types de commentaires SQL

En fonction de vos besoins et de vos préférences, il existe trois façons d'ajouter des commentaires dans les scripts SQL.

Commentaires sur une seule ligne

Si votre commentaire tient sur une seule ligne, utilisez des doubles tirets. En règle générale, vous placez ces commentaires au-dessus du bloc de code concerné afin d'en préciser le contexte.

--select the department name from the department table
SELECT dept_name
FROM employees.departments;

Commentaires en ligne

Comme le montre l'exemple suivant, les commentaires en ligne et à ligne unique en SQL utilisent la même syntaxe et sont essentiellement les mêmes ; la différence réside dans l'endroit et la manière dont ils sont placés. Les commentaires en ligne sont généralement utilisés pour expliquer une partie spécifique de la requête.

SELECT DISTINCT title -- It excludes duplicate titles using the DISTINCT keyword.
FROM employees.titles
ORDER BY title ASC -- The results are sorted alphabetically by the 'title' column.
LIMIT 10;

Commentaires multilignes ou commentaires en bloc

Vous pouvez utiliser les commentaires multilignes en SQL pour ajouter des commentaires plus longs sur plusieurs lignes. Pour ajouter des commentaires sur plusieurs lignes, insérez votre texte entre /* et */. L'interpréteur SQL ignorera tout texte compris entre /* et */.

/*
This query retrieves the employee number, first name, last name, and gender
from the 'employees' table in the 'employees' database.
It filters the results only to include male employees, limiting to 4 rows.
*/
SELECT emp_no, first_name, last_name, gender
FROM employees.employees
WHERE employees.employees.gender = 'M'
LIMIT 4;

Meilleures pratiques pour la rédaction de commentaires SQL

Pour que vos commentaires soient à la fois concis et informatifs dans l'ensemble de votre base de code, il est important de respecter les meilleures pratiques. Passons en revue quelques-unes des lignes directrices ci-dessous. 

Clarté et lisibilité

Évitez d'utiliser des termes trop complexes ou techniques dans vos commentaires. Cela garantit qu'ils sont clairs et concis afin que tout le monde puisse les comprendre, même ceux qui ne sont pas familiers avec la base de code.

Ajouter des informations pertinentes

Assurez-vous que les informations que vous fournissez sont exactes et en rapport direct avec le code qu'elles décrivent. Il doit expliquer le raisonnement qui sous-tend une logique complexe. Évitez d'inclure des informations sensibles dans les commentaires, telles que les mots de passe et les clés API.

Mise à jour régulière

Les commentaires périmés peuvent induire en erreur et contribuer à la dette technique. C'est pourquoi vous devez revoir et mettre à jour vos commentaires au fur et à mesure que vous mettez à jour le code pour refléter les dernières modifications.

Évitez la redondance

Les commentaires ne doivent pas se contenter de répéter ce que fait le code. Les commentaires doivent plutôt expliquer le "pourquoi" du code, c'est-à-dire l'objectif ou le contexte qui n'est pas immédiatement apparent dans le code lui-même.

Erreurs courantes dans les commentaires SQL

Commenter votre code SQL est très important pour garder les choses organisées et compréhensibles, surtout si vous devez revisiter votre code des mois plus tard. Mais même avec les meilleures intentions, il est facile de tomber dans des pièges qui rendent vos commentaires plus confus qu'utiles. Voici quelques erreurs courantes à éviter lors de la rédaction de commentaires SQL :

Commentaires ambigus ou trompeurs

Rédigez des commentaires concis et sans ambiguïté qui apportent une valeur ajoutée au lecteur. Les commentaires imprécis ou inexacts sont pires que l'absence de commentaires.

Code sur-commenté

Si les commentaires sont utiles, l'excès de commentaires peut rendre le code plus difficile à lire et à maintenir. Essayez de vous concentrer sur l'explication de l'objectif de haut niveau et des aspects non évidents du code.

Prenons un mauvais exemple :

Mauvais exemple de commentaire en SQL

Commentaire dans une requête SQL. Image par l'auteur.

Comme nous pouvons le constater, nos variables ayant des noms explicites, les commentaires ne font que reprendre le code sans fournir de contexte supplémentaire ni expliquer son objectif.

Un style de commentaire incohérent

Les styles incohérents sont gênants et rendent le code plus difficile à lire. Pour éviter cela, utilisez un style de commentaire cohérent dans l'ensemble de votre base de code. 

  • Capitalisation : Le maintien d'une capitalisation cohérente facilite la lecture et la compréhension de votre code.
  • La ponctuation : Terminer tous les commentaires par des points peut être une bonne pratique, mais ce n'est pas une règle stricte. L'objectif principal est la cohérence.
  • Formatage : En définissant des lignes directrices claires concernant l'utilisation des commentaires en bloc et des commentaires en ligne, vous garantissez la cohérence.

Absence de contexte

L'exemple suivant comprend une description de haut niveau de l'objectif de notre code SQL : "Récupérer les commandes des clients pour l'établissement de rapports". Bien qu'il soit exact, il manque le contexte nécessaire pour aider le lecteur à comprendre pleinement le code.

/*
* Retrieve employees' data for reporting
*/
SELECT e.first_name, e.last_name, s.salary
FROM employees.employees e
JOIN employees.salaries s ON e.emp_no = s.emp_no
WHERE s.salary > 150000
ORDER BY s.salary DESC;

Pour améliorer notre commentaire, nous pouvons le mettre à jour en y incluant plus de détails.

/* Retrieve employees' names and salaries where salary is above $150,000
as part of the monthly HR reporting process.
*/
SELECT e.first_name, e.last_name, s.salary
FROM employees.employees e
JOIN employees.salaries s ON e.emp_no = s.emp_no
WHERE s.salary > 150000
ORDER BY s.salary DESC;

Utilisations avancées des commentaires SQL

En plus d'améliorer la lisibilité, les commentaires SQL facilitent également le processus de codage. Dans cette section, nous explorons les utilisations avancées des commentaires SQL, notamment l'intégration de métadonnées, le débogage du code SQL et la désactivation temporaire du code. Ces techniques permettent de rationaliser le codage, ce qui facilite la gestion et le dépannage de vos scripts SQL.

Intégrer des métadonnées

Vous pouvez utiliser les commentaires pour intégrer des métadonnées sur le code SQL, telles que le nom de l'auteur et la date de création ou de modification.

/*
Author: DataCamp
Date: 2024-05-28
Purpose: Retrieve employees' credentials for their record
*/
SELECT emp_no, first_name, last_name
FROM employees.employees

Débogage du code SQL

Vous pouvez commenter des sections de votre code SQL pour isoler et tester des parties spécifiques. Cela peut vous aider à déterminer où se situe le problème.

/*SELECT * FROM Customers;
SELECT * FROM Products;
SELECT * FROM Orders;*/
SELECT * FROM Categories;

Désactivation temporaire du code

Vous pouvez désactiver temporairement le code SQL en utilisant des commentaires d'une seule ligne (--) ou des commentaires multilignes en SQL (/* ... */). De cette façon, vous pouvez conserver le code dans la requête sans l'exécuter, ce qui peut être utile pour tester uniquement des parties spécifiques de votre code SQL.

SELECT column1, column2
FROM table1
WHERE condition1
/*
AND condition2
OR condition3
*/

Mythes et idées fausses

Malgré son utilisation répandue, les commentaires SQL font l'objet de quelques mythes et idées fausses persistants.

Mythe n°. Myth Réalité
1 Les commentaires SQL ralentissent l'exécution. Le moteur SQL ignore les commentaires, qui n'ont donc aucun impact sur les performances.
2 Les commentaires SQL rendent le code plus difficile à lire et à comprendre. Les commentaires bien rédigés ont l'effet inverse : Ils peuvent faciliter la lecture du code.
3 Les commentaires SQL ne sont utiles que pour les débutants. Même les développeurs expérimentés peuvent tirer profit de commentaires bien rédigés, en particulier lorsqu'ils travaillent sur des requêtes complexes ou qu'ils revoient du code après une longue période.

Réflexions finales

Bien que cela puisse sembler insignifiant pour le développement SQL, les commentaires peuvent améliorer le code et le rendre plus facile à comprendre. En écrivant des commentaires clairs et bien structurés, les développeurs peuvent s'assurer que leur code SQL reste accessible même des années après sa création initiale.

Si vous commencez tout juste votre voyage en SQL, comprendre les bases grâce à un cours comme SQL Fundamentals peut vous aider à saisir l'importance des commentaires dès le début. Au fur et à mesure de votre progression, l'obtention d'une certification SQL Associate valide vos compétences et montre que vous êtes capable d'écrire un code clair et bien documenté. Pour améliorer encore vos compétences, SQL Intermédiaire se penche sur des requêtes plus complexes dans lesquelles des commentaires détaillés peuvent être utilisés pour le débogage, par exemple.


Laiba Siddiqui's photo
Author
Laiba Siddiqui
LinkedIn
Twitter

Je suis un stratège du contenu qui aime simplifier les sujets complexes. J'ai aidé des entreprises comme Splunk, Hackernoon et Tiiny Host à créer un contenu attrayant et informatif pour leur public.

Questions fréquemment posées

Comment puis-je m'assurer que mes commentaires SQL sont compréhensibles par les nouveaux membres de l'équipe ?

Utilisez des commentaires clairs et descriptifs qui expliquent efficacement l'objectif et la fonctionnalité du code.

Comment les commentaires SQL facilitent-ils le débogage ?

Les commentaires SQL peuvent faciliter le débogage en fournissant un contexte de code supplémentaire. Cela permet d'identifier et de corriger les erreurs plus efficacement.

Les commentaires SQL sont-ils nécessaires pour toutes les requêtes SQL ?

Non, les commentaires SQL ne sont pas nécessaires pour toutes les requêtes SQL. Cependant, ils sont fortement recommandés pour les requêtes complexes et pour les requêtes qui sont difficiles à comprendre sans contexte supplémentaire.

Existe-t-il des outils ou des interfaces spécifiques qui imposent des restrictions supplémentaires aux commentaires ?

Certains outils, comme SQLPlus, peuvent avoir des restrictions supplémentaires sur les commentaires. Par exemple, SQLPlus n'autorise pas la présence d'une ligne blanche à l'intérieur d'un commentaire multiligne.

Est-il vrai que seuls les débutants doivent écrire des commentaires en SQL ?

Non, même les développeurs expérimentés tirent profit de commentaires bien rédigés, en particulier lorsqu'ils travaillent sur des requêtes complexes ou qu'ils revoient du code après une longue période.

Sujets

Apprenez SQL avec DataCamp

cours

Introduction to SQL

2 hr
974.1K
Learn how to create and query relational databases using SQL in just two hours.
Afficher les détailsRight Arrow
Commencer le cours
Voir plusRight Arrow
Apparenté

blog

Les 20 meilleures questions d'entretien pour les flocons de neige, à tous les niveaux

Vous êtes actuellement à la recherche d'un emploi qui utilise Snowflake ? Préparez-vous à répondre à ces 20 questions d'entretien sur le flocon de neige pour décrocher le poste !
Nisha Arya Ahmed's photo

Nisha Arya Ahmed

20 min

blog

Les 32 meilleures questions d'entretien sur AWS et leurs réponses pour 2024

Un guide complet pour explorer les questions d'entretien AWS de base, intermédiaires et avancées, ainsi que des questions basées sur des situations réelles. Il couvre tous les domaines, garantissant ainsi une stratégie de préparation bien équilibrée.
Zoumana Keita 's photo

Zoumana Keita

30 min

blog

2022-2023 Rapport annuel DataCamp Classrooms

À l'aube de la nouvelle année scolaire, DataCamp Classrooms est plus motivé que jamais pour démocratiser l'apprentissage des données, avec plus de 7 650 nouveaux Classrooms ajoutés au cours des 12 derniers mois.
Nathaniel Taylor-Leach's photo

Nathaniel Taylor-Leach

8 min

blog

Q2 2023 DataCamp Donates Digest

DataCamp Donates a offert plus de 20k bourses d'études à nos partenaires à but non lucratif au deuxième trimestre 2023. Découvrez comment des apprenants défavorisés et assidus ont transformé ces opportunités en réussites professionnelles qui ont changé leur vie.
Nathaniel Taylor-Leach's photo

Nathaniel Taylor-Leach

blog

Nous avons fait don de bourses DataCamp Premium à un million de personnes, et ce n'est pas fini.

Réparties entre nos deux programmes d'impact social, DataCamp Classrooms et #DCDonates, les bourses offrent un accès illimité à tout ce que DataCamp Premium a à offrir.
Nathaniel Taylor-Leach's photo

Nathaniel Taylor-Leach

blog

Célébration de Saghar Hazinyar : Une boursière de DataCamp Donates et une diplômée de Code to Inspire

Découvrez le parcours inspirant de Saghar Hazinyar, diplômée de Code to Inspire, qui a surmonté les défis en Afghanistan et s'est épanouie grâce à une bourse de DataCamp Donates.
Fereshteh Forough's photo

Fereshteh Forough

4 min

Voir plusVoir plus