Comment créer des commentaires en SQL

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 :

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.

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.