SQL Comments: A Comprehensive Guide

In the world of SQL (Structured Query Language), comments play a crucial role in making code more understandable, maintainable, and collaborative. Comments are non - executable lines of text that can be added to SQL scripts. They serve as notes for developers, database administrators, or anyone who might be working with the SQL code in the future. This blog post will provide a detailed overview of SQL comments, including their types, common practices, best practices, and example usage.

Table of Contents#

  1. Types of SQL Comments
  2. Single - Line Comments
    • Syntax
    • Example Usage
  3. Multi - Line Comments
    • Syntax
    • Example Usage
  4. Common Practices
    • Commenting in Stored Procedures
    • Commenting in Views
  5. Best Practices
    • Keep Comments Concise
    • Update Comments Regularly
    • Use Consistent Commenting Style
  6. Conclusion
  7. References

1. Types of SQL Comments#

There are two main types of SQL comments: single - line comments and multi - line comments. Each type has its own syntax and use cases.

2. Single - Line Comments#

Syntax#

The syntax for single - line comments varies depending on the database management system (DBMS). Here are the common ways to write single - line comments:

  • In MySQL, PostgreSQL, and SQLite, you can use two hyphens (--) to start a single - line comment. Anything after the -- on the same line is considered a comment.
-- This is a single - line comment in MySQL, PostgreSQL, and SQLite
SELECT * FROM users;
  • In SQL Server, you can use two hyphens (--) to start a single - line comment. Anything after the -- on the same line is considered a comment.
-- This is a single - line comment in SQL Server
SELECT * FROM employees;

Example Usage#

Single - line comments are often used to provide quick explanations for a specific query or a part of a query. For example:

-- Select all customers from the 'customers' table
SELECT * FROM customers;
 
-- Filter customers from the 'USA'
SELECT * FROM customers WHERE country = 'USA';

3. Multi - Line Comments#

Syntax#

Multi - line comments are used when you need to write longer explanations that span multiple lines. The syntax for multi - line comments is similar across different DBMS. You start the comment with /* and end it with */.

/*
This is a multi - line comment.
It can span multiple lines and is useful for providing detailed explanations.
*/
SELECT * FROM products;

Example Usage#

Multi - line comments are great for providing documentation for a block of code, such as a complex query or a stored procedure. For example:

/*
This query retrieves the total number of orders
for each customer in the 'orders' table.
It groups the results by customer ID and counts the number of orders.
*/
SELECT customer_id, COUNT(order_id) AS total_orders
FROM orders
GROUP BY customer_id;

4. Common Practices#

Commenting in Stored Procedures#

Stored procedures are pre - compiled SQL code that can be executed repeatedly. When writing stored procedures, it's important to add comments to explain the purpose of the procedure, its input and output parameters, and any complex logic inside.

/*
Procedure: GetCustomerOrders
Purpose: Retrieve all orders for a given customer ID
Input: customer_id (INT) - The ID of the customer
Output: A result set containing order details
*/
CREATE PROCEDURE GetCustomerOrders
    @customer_id INT
AS
BEGIN
    -- Select all orders for the given customer ID
    SELECT * FROM orders WHERE customer_id = @customer_id;
END;

Commenting in Views#

Views are virtual tables based on the result of a SQL query. Comments in views can help other developers understand the purpose of the view and how the data is being selected and transformed.

/*
View: CustomerSummary
Purpose: Provide a summary of customer information, including the total number of orders
*/
CREATE VIEW CustomerSummary AS
-- Select customer ID, name, and the total number of orders
SELECT c.customer_id, c.customer_name, COUNT(o.order_id) AS total_orders
FROM customers c
LEFT JOIN orders o ON c.customer_id = o.customer_id
GROUP BY c.customer_id, c.customer_name;

5. Best Practices#

Keep Comments Concise#

Comments should be short and to the point. Avoid writing overly long comments that repeat what the code is doing. Instead, focus on explaining the why behind the code, such as business requirements or design decisions.

Update Comments Regularly#

As the code evolves, make sure to update the comments accordingly. Outdated comments can be more confusing than no comments at all.

Use Consistent Commenting Style#

Adopt a consistent commenting style throughout your SQL codebase. This makes it easier for other developers to read and understand your code. For example, use a specific format for single - line and multi - line comments, and always start comments with a capital letter.

6. Conclusion#

SQL comments are an essential part of writing clean, maintainable, and collaborative SQL code. By using single - line and multi - line comments effectively, you can make your code more understandable for yourself and others. Following common and best practices for commenting will help you create high - quality SQL scripts that are easy to work with in the long run.

7. References#

2026-07