SQL Notes
Learn SQL comments, their types, syntax, use cases, best practices, and how comments improve code readability and database maintenance.
As your SQL queries get bigger and messier, figuring out what they actually do becomes a pain. A query that makes sense today might be total gibberish in six months—especially if you're working in a team or maintaining legacy database projects.
That's where SQL comments come in.
Comments let you add notes, explanations, and documentation directly in your SQL code without breaking anything. They make your code easier to read, maintain, debug, and share with your team.
In this lesson, you'll learn what comments are, why they matter, the different types, and how professionals document SQL scripts.
Why Are Comments Important?
A lot of beginners think comments are overkill for small projects.
But real-world databases have:
- Hundreds of tables
- Thousands of queries
- Complex reports
- Stored procedures
- Triggers
- Views
Without comments, old code becomes a nightmare to understand.
Comments help you:
- Explain what a query does
- Document business rules
- Improve readability
- Simplify maintenance
- Help your team collaborate
- Speed up debugging
Real-World Example
Picture a company database with thousands of employee records.
Without comments:
SELECT *
FROM Employees
WHERE Salary > 50000;The query works fine. But does another dev know *why* it exists?
With comments:
-- Retrieve employees eligible for annual bonus review
SELECT *
FROM Employees
WHERE Salary > 50000;Now it's obvious. One tiny comment saves hours later.
Types of SQL Comments
SQL supports two comment styles.
Single-Line Comments
Use these for quick notes.
They start with:
--Everything after the double hyphen on that line becomes a comment.
Example:
-- Display all students
SELECT * FROM Students;The database ignores the comment and runs the query.
How Single-Line Comments Work
Look at this:
SELECT *
FROM Students; -- Fetch student informationThe comment sits after the SQL statement.
The database processes:
SELECT *
FROM Students;and tosses:
Fetch student information
Great for quick explanations.
Multiple Single-Line Comments
You can stack them:
-- Select student names
-- Filter active students
SELECT Name
FROM Students;Each line with -- is its own comment. Perfect for explaining script steps.
Multi-Line Comments
When you need more explanation, use multi-line comments.
They start with:
/*and end with:
*/Everything in between is a comment.
Example:
/*
This query retrieves all students
who have completed registration
for the current academic year.
*/
SELECT *
FROM Students;The database skips the whole block.
Why Use Multi-Line Comments?
Use them when you're:
- Describing complex queries
- Documenting business logic
- Writing deployment notes
- Explaining stored procedures
- Creating SQL documentation
Example:
/*
Report Name: Monthly Sales Report
Purpose:
Calculate total sales generated
during the current month.
Department:
Finance
*/
SELECT *
FROM Sales;This puts professional documentation right in your SQL script.
Commenting Out SQL Code
Comments are super useful during testing.
Instead of deleting code, just comment it out:
-- DELETE FROM Students;
SELECT * FROM Students;The DELETE won't run because it's commented out. You can experiment safely without losing your code.
Testing Queries Using Comments
Say you're working on a query:
SELECT Name,
Age,
Address
FROM Students;You want to test it without showing addresses. Instead of deleting the column:
SELECT Name,
Age
-- Address
FROM Students;The commented part gets skipped. Testing becomes faster and safer.
Using Comments in Large SQL Scripts
Database admins often work with scripts that are hundreds of lines long.
Comments help break it into sections:
-- =====================================
-- Student Management System Database
-- =====================================
-- Create Students Table
CREATE TABLE Students (
StudentID INT PRIMARY KEY,
Name VARCHAR(100)
);
-- Create Courses Table
CREATE TABLE Courses (
CourseID INT PRIMARY KEY,
CourseName VARCHAR(100)
);Way easier to navigate.
Comments in Stored Procedures
Stored procedures get complex fast.
Comments explain what's happening:
/*
Calculate yearly bonus
for eligible employees.
*/
CREATE PROCEDURE CalculateBonus
AS
BEGIN
-- Update employee bonus
UPDATE Employees
SET Bonus = Salary * 0.10;
END;Without comments, figuring out what this does takes forever.
Comments in Team Projects
Comments become gold when multiple devs are working together.
Benefits:
Better Communication
Comments explain the "why" clearly.
Faster Onboarding
New devs understand the project quicker.
Easier Maintenance
Future updates are simpler.
Reduced Confusion
Less time spent reverse-engineering old code.
Common Mistakes When Using Comments
Comments are useful, but misused comments create problems.
Writing Obvious Comments
Bad:
-- Select data
SELECT * FROM Students;That's... obvious.
Better:
-- Retrieve students enrolled for the current semester
SELECT * FROM Students;Comments should add value.
Outdated Comments
A dangerous situation happens when comments stop matching the code.
Example:
-- Retrieves active students
SELECT * FROM Students;Later, you change it to get *all* students. Now the comment lies. Always keep comments updated.
Excessive Comments
Not every line needs explanation.
Bad:
-- Select Name column
Name,
-- Select Age column
AgeOver-commenting reduces readability. Focus on explaining *logic*, not obvious syntax.
Best Practices for SQL Comments
Professional devs follow a few rules.
Explain Why, Not What
Instead of:
-- Select employees
SELECT * FROM Employees;Do this:
-- Retrieve employees eligible for promotion review
SELECT * FROM Employees;Keep Comments Short
Informative but concise.
Update Comments Regularly
When code changes, update the comments too.
Use Multi-Line Comments for Documentation
For big explanations:
/*
...
*/not a bunch of single-line comments.
Group Sections with Comments
Large scripts are easier to navigate when you break them into sections.
SQL Comments Across Different Databases
Most databases support standard SQL comments:
- MySQL
- PostgreSQL
- SQL Server
- Oracle Database
- SQLite
- MariaDB
The syntax is pretty consistent. Comments port between different databases easily.
Real-World Use Cases
Comments show up in:
Reporting Queries
Explain report calculations.
Data Migration Scripts
Document migration steps.
Database Maintenance
Describe cleanup operations.
Stored Procedures
Clarify business rules.
Triggers
Explain automatic actions.
Enterprise Systems
Provide documentation for future devs.
Summary
SQL comments are essential for writing professional, maintainable SQL code. They let you document logic, explain business needs, organize scripts, and help your team without affecting queries.
In this lesson, you learned:
- What SQL comments are
- Why they matter
- Single-line comments
- Multi-line comments
- Commenting out code
- Common mistakes
- Best practices
- Real-world usage
Good comments make SQL easy to understand now and easy to maintain later.
Next Step
Continue to the next lesson:
Exam Focus
Revise definitions, diagrams, examples, and short-answer points for SQL Comments.
Interview Use
Prepare one clear explanation, one practical example, and one common mistake for this SQL Complete Guide topic.
Search Terms
sql-complete-guide, sql complete guide, sql, complete, guide, basics, comments, sql comments
Related SQL Complete Guide Topics