SQL Topics
SQL Comments
title: SQL Comments
As SQL queries become larger and more complex, understanding the purpose of every statement can become difficult. A query that makes perfect sense today may become confusing after a few months, especially when working in teams or maintaining old database projects.
This is where SQL comments become important.
Comments allow developers to add notes, explanations, and documentation directly inside SQL code without affecting query execution. They make code easier to understand, maintain, debug, and share with other developers.
In this lesson, you will learn what SQL comments are, why they are useful, the different types of comments, and the best practices professionals follow when documenting SQL scripts.
What Are SQL Comments?
SQL comments are pieces of text written inside SQL code that are ignored by the database engine during execution.
When SQL encounters a comment, it skips that text completely and executes only the actual SQL statements.
For example:
-- Retrieve all student records
SELECT * FROM Students;In this query:
-- Retrieve all student recordsis a comment.
The database executes only:
SELECT * FROM Students;Comments exist purely for humans, not for the database.
Why Are Comments Important?
Many beginners believe comments are unnecessary for small projects.
However, professional databases often contain:
- Hundreds of tables
- Thousands of queries
- Complex reports
- Stored procedures
- Triggers
- Views
Without comments, understanding old code becomes extremely difficult.
Comments help developers:
- Explain query purpose
- Document business rules
- Improve readability
- Simplify maintenance
- Assist team collaboration
- Reduce debugging time
Real-World Example
Imagine a company database containing thousands of employees.
Without comments:
SELECT *
FROM Employees
WHERE Salary > 50000;The query works, but another developer may not know why it exists.
With comments:
-- Retrieve employees eligible for annual bonus review
SELECT *
FROM Employees
WHERE Salary > 50000;Now the purpose is immediately clear.
This simple addition can save significant time during maintenance.
Types of SQL Comments
SQL supports two main comment styles.
Single-Line Comments
Single-line comments are used for short explanations.
They begin with:
--Everything after the double hyphen on the same line becomes a comment.
Example:
-- Display all students
SELECT * FROM Students;The database ignores the comment and executes only the query.
How Single-Line Comments Work
Consider the following example:
SELECT *
FROM Students; -- Fetch student informationThe comment appears after the SQL statement.
The database processes:
SELECT *
FROM Students;and ignores:
Fetch student informationThis approach is useful for brief explanations.
Multiple Single-Line Comments
You can write multiple comments.
Example:
-- Select student names
-- Filter active students
SELECT Name
FROM Students;Each line beginning with -- is treated as a separate comment.
This style is often used to explain steps in a script.
Multi-Line Comments
When explanations become longer, multi-line comments are preferred.
They begin with:
/*and end with:
*/Everything between these symbols becomes a comment.
Example:
/*
This query retrieves all students
who have completed registration
for the current academic year.
*/
SELECT *
FROM Students;The database ignores the entire comment block.
Why Use Multi-Line Comments?
Multi-line comments are useful when:
- 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 creates professional documentation directly inside the SQL script.
Commenting Out SQL Code
Comments are frequently used during testing.
Instead of deleting code, developers temporarily disable it.
Example:
-- DELETE FROM Students;
SELECT * FROM Students;The DELETE statement will not execute because it is commented out.
This allows safe experimentation without losing code.
Testing Queries Using Comments
Suppose a developer is working on a query:
SELECT Name,
Age,
Address
FROM Students;They want to test the query without displaying addresses.
Instead of removing the column:
SELECT Name,
Age
-- Address
FROM Students;The commented portion is ignored.
This makes testing faster and safer.
Using Comments in Large SQL Scripts
Database administrators often work with scripts containing hundreds of lines.
Comments help divide scripts into sections.
Example:
-- =====================================
-- 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)
);The script becomes much easier to navigate.
Comments in Stored Procedures
Stored procedures often contain complex business logic.
Comments help explain important operations.
Example:
/*
Calculate yearly bonus
for eligible employees.
*/
CREATE PROCEDURE CalculateBonus
AS
BEGIN
-- Update employee bonus
UPDATE Employees
SET Bonus = Salary * 0.10;
END;Without comments, understanding the procedure may take significantly longer.
Comments in Team Projects
When multiple developers work together, comments become even more valuable.
Benefits include:
Better Communication
Comments explain intentions clearly.
Faster Onboarding
New developers understand the project quickly.
Easier Maintenance
Future updates become simpler.
Reduced Confusion
Developers spend less time interpreting old code.
Common Mistakes When Using Comments
Although comments are useful, they can also create problems when misused.
Writing Obvious Comments
Poor example:
-- Select data
SELECT * FROM Students;The query already makes this obvious.
Better:
-- Retrieve students enrolled for the current semester
SELECT * FROM Students;Comments should add value.
Outdated Comments
A dangerous situation occurs when comments no longer match the code.
Example:
-- Retrieves active students
SELECT * FROM Students;If the query later changes to retrieve all students, the comment becomes misleading.
Always keep comments updated.
Excessive Comments
Not every line requires explanation.
Bad example:
-- Select Name column
Name,
-- Select Age column
AgeOver-commenting can reduce readability.
Focus on explaining logic, not obvious syntax.
Best Practices for SQL Comments
Professional developers follow several guidelines.
Explain Why, Not What
Instead of:
-- Select employees
SELECT * FROM Employees;Use:
-- Retrieve employees eligible for promotion review
SELECT * FROM Employees;Keep Comments Short
Comments should be informative but concise.
Update Comments Regularly
Whenever code changes, review associated comments.
Use Multi-Line Comments for Documentation
Large explanations should use:
/*
...
*/instead of many single-line comments.
Group Sections with Comments
Large scripts become easier to navigate when divided into logical sections.
SQL Comments Across Different Databases
Most database systems support standard SQL comments.
Examples include:
- MySQL
- PostgreSQL
- SQL Server
- Oracle Database
- SQLite
- MariaDB
The comment syntax remains largely consistent across platforms.
This makes comments portable between different database systems.
Real-World Use Cases
Comments are commonly used 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 developers.
Summary
SQL comments are an essential tool for writing professional, maintainable, and understandable database code. They allow developers to document logic, explain business requirements, organize scripts, and improve collaboration without affecting query execution.
In this lesson, you learned:
- What SQL comments are
- Why comments are important
- Single-line comments
- Multi-line comments
- Commenting out code
- Common mistakes
- Best practices
- Real-world usage
Well-written comments make SQL code easier to understand today and easier to maintain in the future.
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 topic.
Search Terms
sql, sql complete guide, sql tutorial, sql notes, complete, guide, basics, comments
Related SQL Topics