Hoe maak je comments in SQL

SQL, wat staat voor Structured Query Language, is een krachtige taal voor het beheren en bewerken van relationele databases. Hoewel SQL-queries op het eerste gezicht vanzelfsprekend kunnen lijken, kunnen comments in SQL-instructies de leesbaarheid en het onderhoud van je code verbeteren.

In deze tutorial laten we zien hoe je comments in SQL toevoegt om je code eenvoudiger en overzichtelijker te maken.

Het korte antwoord: hoe maak je comments in SQL

Er zijn drie manieren om comments aan je SQL-queries toe te voegen:

1. Opmerkingen op één regel: Comments op één regel beginnen met -- (twee mintekens).

2. Inline comments: Inline comments beginnen met -- na de SQL-instructie op dezelfde regel.

3. Meerregelige of blokcomments: Meerregelige comments beginnen met /* en eindigen met */.

 -- Single line comment
SELECT * 
FROM TABLE

SELECT * 
FROM TABLE -- Inline comment

/* Multiline
comment */ 
SELECT * 
FROM TABLE  Mogelijk gemaakt door

Waarom zijn SQL-comments belangrijk?

Hier zijn drie belangrijke redenen waarom SQL-comments belangrijk zijn:

• De bedoeling van de code verduidelijken: Comments leggen het doel en de logica van de code uit, zodat jij en anderen deze later gemakkelijker begrijpen wanneer je je code opnieuw bekijkt.
• Betere samenwerking: Comments bevorderen teamwork door de code te documenteren voor andere developers, zodat zij je werk beter kunnen volgen.
• Hulp bij debuggen en optimaliseren: Comments maken het op termijn eenvoudiger om te debuggen en te optimaliseren, waardoor problemen makkelijker te vinden en te corrigeren zijn.

Soorten SQL-comments

Afhankelijk van je behoeften en voorkeuren zijn er drie manieren om comments toe te voegen in SQL-scripts.

Opmerkingen op één regel

Als je comment goed binnen één regel past, gebruik je dubbele mintekens. Meestal plaats je zulke comments boven het relevante codeblok om context te geven.

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

Inline comments

Zoals we in het volgende voorbeeld zien, gebruiken opmerkingen op één regel en inline comments in SQL dezelfde syntaxis en komen ze in essentie op hetzelfde neer; het verschil zit in waar en hoe ze worden geplaatst. Inline comments worden vaak gebruikt om een specifiek deel van de query toe te lichten.

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;
Mogelijk gemaakt door

Meerregelige of blokcomments

Je kunt meerregelige comments in SQL gebruiken om langere opmerkingen over meerdere regels toe te voegen. Om meerregelige comments toe te voegen, zet je je tekst tussen /* en */. De SQL-interpreter negeert alle tekst die tussen /* en */ staat.

/*
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;
Mogelijk gemaakt door

Best practices voor het schrijven van SQL-comments

Om ervoor te zorgen dat je comments in je hele codebase zowel beknopt als informatief zijn, is het belangrijk om best practices te volgen. Laten we hieronder enkele richtlijnen doornemen. 

Duidelijkheid en leesbaarheid

Vermijd al te complexe of technisch jargon in je comments. Zo blijven ze helder en beknopt, zodat iedereen ze kan begrijpen, ook wie niet bekend is met de codebase.

Voeg relevante informatie toe

Zorg ervoor dat de informatie die je geeft accuraat is en direct relevant voor de code die je beschrijft. Leg de redenatie achter complexe logica uit. Vermijd gevoelige informatie in comments, zoals wachtwoorden en API-sleutels.

Regelmatig bijwerken

Verouderde comments kunnen misleiden en bijdragen aan technische schuld. Daarom moet je comments nakijken en bijwerken wanneer je de code aanpast, zodat ze de laatste wijzigingen weerspiegelen.

Vermijd overbodigheid

Comments moeten niet simpelweg herhalen wat de code doet. Leg in plaats daarvan het "waarom" achter de code uit: het doel of de context die niet direct uit de code zelf blijkt.

Veelvoorkomende fouten bij SQL-comments

Comments toevoegen aan je SQL-code is superbelangrijk om alles georganiseerd en begrijpelijk te houden, vooral als je je code na maanden weer bekijkt. Maar zelfs met de beste bedoelingen is het makkelijk om in valkuilen te stappen waardoor je comments eerder verwarren dan helpen. Dit zijn veelvoorkomende fouten die je moet vermijden bij het schrijven van SQL-comments:

Ambigue of misleidende comments

Schrijf beknopte en eenduidige comments die waarde bieden voor de lezer. Onduidelijke of onjuiste comments zijn erger dan geen comments.

Te veel commentaar

Hoewel comments nuttig zijn, kan te veel commentaar de code lastiger leesbaar en onderhoudbaar maken. Richt je op het uitleggen van het hoofddoel en de niet-voor-de-hand-liggende aspecten van de code.

Laten we een slecht voorbeeld bekijken:

Comment in een SQL-query. Afbeelding door de auteur.

Zoals we zien, omdat onze variabelen duidelijke namen hadden, herhaalden de comments enkel de code zonder extra context te geven of het doel uit te leggen.

Inconsistente commentstijl

Inconsistente stijlen leiden af en maken de code moeilijker te lezen. Gebruik daarom in je hele codebase een consistente commentaarstijl. 

• Hoofdletters: Consequente kapitalisatie maakt je code makkelijker leesbaar en begrijpelijk.
• Interpunctie: Alle comments eindigen met een punt kan een goede gewoonte zijn, maar het is geen strikte regel. Het belangrijkste is consistentie.
• Opmaak: Door duidelijke richtlijnen te definiëren voor het gebruik van blokcomments versus inline comments, zorg je voor consistentie.

Gebrek aan context

Het volgende voorbeeld bevat een beschrijving op hoofdlijnen van het doel van onze SQL-code: "Klantorders ophalen voor rapportage." Hoewel correct, mist het de context die de lezer helpt de code volledig te begrijpen.

/*
* 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;
Mogelijk gemaakt door

Om onze comment te verbeteren, kunnen we deze bijwerken met meer details.

/* 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;
Mogelijk gemaakt door

Geavanceerde toepassingen van SQL-comments

Naast het verbeteren van de leesbaarheid helpen SQL-comments ook tijdens het coderen. In dit deel verkennen we geavanceerde toepassingen van SQL-comments, zoals het insluiten van metadata, debuggen van SQL-code en tijdelijk uitschakelen van code. Deze technieken stroomlijnen het coderen, zodat je je SQL-scripts effectiever kunt beheren en troubleshooten.

Metadata insluiten

Je kunt comments gebruiken om metadata over de SQL-code op te nemen, zoals de naam van de auteur en de datum van aanmaak of wijziging.

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

SQL-code debuggen

Je kunt delen van je SQL-code uitcommentariëren om specifieke onderdelen te isoleren en te testen. Dit kan helpen om te achterhalen waar een probleem zich voordoet.

/*SELECT * FROM Customers;
SELECT * FROM Products;
SELECT * FROM Orders;*/
SELECT * FROM Categories;
Mogelijk gemaakt door

Code tijdelijk uitschakelen

Je kunt SQL-code tijdelijk uitschakelen met comments op één regel (--) of met meerregelige comments in SQL (/* ... */). Zo kun je de code in de query laten staan zonder deze uit te voeren, wat handig is om alleen specifieke delen van je SQL-code te testen.

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

Mythes en misvattingen

Ondanks het wijdverbreide gebruik zijn er een paar hardnekkige mythes en misvattingen over SQL-comments.

Tot slot

Hoewel het misschien onbelangrijk lijkt voor SQL-ontwikkeling, kunnen comments de code verbeteren en begrijpelijker maken. Door duidelijke en goed gestructureerde comments te schrijven, zorg je ervoor dat je SQL-code toegankelijk blijft, zelfs jaren na de eerste oplevering.

Als je net begint met SQL, helpt een cursus zoals SQL Fundamentals je de basis te begrijpen en al vroeg het belang van comments te zien. Naarmate je vordert, toont een SQL Associate Certification je vaardigheden aan en laat het zien dat je duidelijke, goed gedocumenteerde code kunt schrijven. Om je skills verder te verbeteren, gaat Intermediate SQL dieper in op complexere queries, waarbij gedetailleerde comments handig zijn voor bijvoorbeeld debuggen.