Come creare commenti in SQL

SQL, acronimo di Structured Query Language, è un linguaggio potente per gestire e manipolare database relazionali. Anche se a prima vista le query SQL possono sembrare autoesplicative, aggiungere commenti nelle istruzioni SQL può migliorare la leggibilità e la manutenibilità del tuo codice.

In questo tutorial vedremo come aggiungere commenti in SQL per rendere il tuo codice più semplice e facile da leggere.

La risposta rapida: come creare commenti in SQL

Ci sono tre modi per aggiungere commenti alle tue query SQL:

1. Commenti su una sola riga: I commenti su una riga iniziano con il doppio trattino --.

2. Commenti inline: I commenti inline iniziano con -- dopo l'istruzione SQL sulla stessa riga.

3. Commenti su più righe o commenti a blocchi: I commenti su più righe iniziano con /* e terminano con */.

 -- Single line comment
SELECT * 
FROM TABLE

SELECT * 
FROM TABLE -- Inline comment

/* Multiline
comment */ 
SELECT * 
FROM TABLE  Offerto da

Perché i commenti SQL sono importanti?

Ecco tre motivi chiave per cui i commenti SQL sono importanti:

• Chiarire lo scopo del codice: I commenti spiegano lo scopo e la logica del codice, rendendo più facile per gli altri e per te stesso capire quando rivedrai il codice in seguito.
• Migliorare il lavoro di squadra: I commenti facilitano il lavoro in team documentando il codice per altri sviluppatori, aiutandoli a comprendere il tuo lavoro.
• Aiutare nel debugging e nell'ottimizzazione: I commenti semplificano il processo di debug e ottimizzazione del codice nel tempo, rendendo più gestibile identificare e correggere i problemi.

Tipi di commenti SQL

A seconda delle tue esigenze e preferenze, ci sono tre modi per aggiungere commenti negli script SQL.

Commenti su una sola riga

Se il tuo commento rientra bene in una sola riga, usa i doppi trattini. In genere, inserirai questi commenti sopra il blocco di codice pertinente per fornire contesto.

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

Commenti inline

Come possiamo vedere nel seguente esempio, i commenti su una riga e quelli inline in SQL usano la stessa sintassi e sono sostanzialmente uguali; la differenza sta in dove e come vengono posizionati. I commenti inline tendono a essere usati per spiegare una parte specifica della query.

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;
Offerto da

Commenti su più righe o commenti a blocchi

Puoi usare i commenti su più righe in SQL per aggiungere commenti più lunghi su più righe. Per aggiungere commenti su più righe, racchiudi il testo tra /* e */. L'interprete SQL ignorerà qualsiasi testo racchiuso tra /* e */.

/*
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;
Offerto da

Best practice per scrivere commenti SQL

Per garantire che i tuoi commenti siano sia concisi sia informativi in tutto il codebase, è importante attenersi alle best practice. Rivediamo alcune linee guida qui sotto. 

Chiarezza e leggibilità

Evita di usare termini eccessivamente complessi o troppo tecnici nei commenti. In questo modo saranno chiari e concisi, così che chiunque possa capirli, anche chi non conosce il codebase.

Aggiungi informazioni rilevanti

Assicurati che le informazioni fornite siano accurate e direttamente pertinenti al codice descritto. Dovrebbero spiegare il ragionamento alla base di logiche complesse. Evita di includere nei commenti informazioni sensibili, come password e chiavi API.

Aggiorna regolarmente

Commenti obsoleti possono fuorviare e contribuire al debito tecnico. Ecco perché dovresti rivedere e aggiornare i commenti quando aggiorni il codice, così da riflettere le modifiche più recenti.

Evita la ridondanza

I commenti non dovrebbero limitarsi a ripetere cosa fa il codice. Dovrebbero invece spiegare il "perché" del codice: lo scopo o il contesto che non è immediatamente evidente dal codice stesso.

Errori comuni nei commenti SQL

Commentare il tuo codice SQL è fondamentale per mantenerlo organizzato e comprensibile, soprattutto se devi tornarci dopo mesi. Ma anche con le migliori intenzioni è facile cadere in trappole che rendono i commenti più confusi che utili. Ecco alcuni errori comuni da evitare quando scrivi commenti SQL:

Commenti ambigui o fuorvianti

Scrivi commenti concisi e non ambigui che apportino valore a chi legge. Commenti poco chiari o imprecisi sono peggio di nessun commento.

Commentare eccessivamente il codice

Sebbene i commenti siano utili, esagerare può rendere il codice più difficile da leggere e mantenere. Cerca di concentrarti sullo spiegare lo scopo ad alto livello e gli aspetti non ovvi del codice.

Vediamo un esempio sbagliato:

Commento in una query SQL. Immagine dell'autore.

Come possiamo vedere, poiché le variabili avevano nomi espliciti, i commenti si limitavano a ripetere il codice senza fornire contesto aggiuntivo o spiegarne lo scopo.

Stile dei commenti incoerente

Stili incoerenti distraggono e rendono il codice più difficile da leggere. Per evitarlo, usa uno stile di commento coerente in tutto il tuo codebase. 

• Maiuscole/minuscole: Mantenere una capitalizzazione coerente rende il codice più facile da leggere e comprendere.
• Punteggiatura: Terminare tutti i commenti con il punto può essere una buona pratica, ma non è una regola ferrea. L'obiettivo principale è la coerenza.
• Formattazione: Definendo linee guida chiare per l'uso dei commenti a blocchi rispetto a quelli inline, garantisci coerenza.

Mancanza di contesto

Il seguente esempio include una descrizione ad alto livello dello scopo del nostro codice SQL: "Recupera gli ordini dei clienti per la reportistica". Sebbene accurata, manca del contesto necessario per aiutare il lettore a comprendere appieno il codice.

/*
* 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;
Offerto da

Per migliorare il nostro commento, possiamo aggiornarlo includendo più dettagli.

/* 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;
Offerto da

Usi avanzati dei commenti SQL

Oltre a migliorare la leggibilità, i commenti SQL aiutano anche nel processo di scrittura del codice. In questa sezione esploriamo usi avanzati dei commenti SQL, tra cui incorporare metadati, fare debug del codice SQL e disabilitare temporaneamente parti di codice. Queste tecniche aiutano a snellire lo sviluppo, rendendo più semplice gestire e risolvere problemi nei tuoi script SQL in modo efficace.

Incorporare metadati

Puoi usare i commenti per incorporare metadati sul codice SQL, come il nome dell'autore e la data di creazione o modifica.

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

Debug del codice SQL

Puoi commentare sezioni del tuo codice SQL per isolare e testare parti specifiche. Questo può aiutarti a individuare il punto in cui si verifica un problema.

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

Disabilitare temporaneamente il codice

Puoi disabilitare temporaneamente del codice SQL usando commenti su una riga (--) o commenti su più righe in SQL (/* ... */). In questo modo puoi mantenere il codice nella query senza eseguirlo, utile per testare solo porzioni specifiche del tuo codice SQL.

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

Miti e idee sbagliate

Nonostante il suo uso diffuso, esistono alcuni miti e idee sbagliate persistenti sui commenti in SQL.

Considerazioni finali

Anche se può sembrare un dettaglio nello sviluppo SQL, i commenti possono migliorare il codice e renderlo più facile da capire. Scrivendo commenti chiari e ben strutturati, gli sviluppatori possono garantire che il loro codice SQL resti accessibile anche a distanza di anni dalla sua creazione iniziale.

Se stai iniziando ora il tuo percorso con SQL, comprendere le basi tramite un corso come SQL Fundamentals può aiutarti a cogliere fin da subito l'importanza dei commenti. Con il progredire, ottenere una SQL Associate Certification convalida le tue competenze e dimostra che sai scrivere codice chiaro e ben documentato. Per migliorare ulteriormente, Intermediate SQL approfondisce query più complesse in cui commenti dettagliati possono essere usati, ad esempio, per il debug.