SQL Comments

SQL comments are non-executable notes written inside SQL code. These notes explain a query, statement, condition, or other part of an SQL script.

A comment can explain what a query does, why a particular condition is used, or provide additional information about the SQL code. For example, consider the following SQL query:

-- Retrieve all employees from the Employees table
SELECT *
FROM Employees;

In this example, the line beginning with — is a comment. It tells users that the query retrieves employee records. The SQL processor ignores the comment when processing the SQL statement and executes the SELECT statement.

SQL comments are written primarily for humans to understand and document SQL code. Developers use comments to make SQL code easier to read, understand, maintain, and debug.

Why Do You Use SQL Comments?

The main purpose of SQL comments is to make SQL code easier to understand, maintain, and debug. You should write SQL comments to:

• Explain the complicated SQL logic.
• Describe the purpose of a query.
• Explain important business rules or conditions.
• Organize large SQL scripts into logical sections.
• Temporarily disable a statement during development or debugging.
• Help other developers understand existing SQL code.

What Makes a Good SQL Comment?

A good SQL comment should provide useful information that helps someone understand the SQL code. It should explain the purpose, reason, or important logic behind the query instead of simply repeating what the SQL statement already shows.

For example, this comment does not provide much useful information:

-- Select customer name
SELECT customer_name
FROM Customers;

The SQL statement already clearly shows that it selects the customer_name column from the Customers table. Therefore, the comment does not add much value.

A more useful comment explains why the query is being used:

-- Display customers who are eligible for the loyalty program
SELECT customer_name
FROM Customers
WHERE loyalty_status = 'Eligible';

Here, the comment provides useful context by explaining the purpose of the query. This makes the code easier for developers to understand and maintain, especially when they work with the code later.

Types of SQL Comments

There are mainly three types of comments in SQL:

• Single-line comments
• Multi-line (block) comments
• Inline comments

Let’s understand each one by one with the help of examples.

Single-Line Comments

A single-line comment is an SQL comment that begins with two hyphens (--) and normally continues until the end of the line. The general syntax to write a single-line comment is:

-- Your comment goes here

The — marker tells the SQL parser that the text following it on that line is a comment.

Example 1:

-- Retrieve all employees
SELECT *
FROM Employees;

Here, — Retrieve all employees is the comment.

When Should You Use Single-Line Comments?

Single-line comments are useful when you want to:

• Explain one SQL statement.
• Describe a condition or calculation.
• Add a short note beside SQL code.
• Temporarily disable a line or multiple lines of SQL during development or debugging.

Best Practice

Keep single-line comments short, meaningful, and close to the SQL they explain.

Multi-Line (Block) Comments

A multi-line comment, also called a block comment, is an SQL comment that can span multiple lines. It begins with /* and ends with */. Everything between /* and */ is treated as a comment and is ignored by the SQL processor.

The general syntax to write multi-line comments in SQL is:

/* Your comment
can continue
across multiple lines.
*/

Example 2:

/*
Retrieve employees
from the IT department
*/
SELECT employee_name
FROM Employees
WHERE department = 'IT';

When Should You Use Multi-Line Comments?

Multi-line comments are useful when you need to:

• Explain complex SQL logic.
• Write longer documentation.
• Add notes covering several lines.
• Temporarily disable a larger section of SQL code.
• Separate major sections of an SQL script.

Best Practice

Use block comments when the explanation genuinely needs multiple lines. Keep the content relevant and maintain it when the underlying SQL logic changes.

Inline Comments

An inline comment is a comment placed on the same line as SQL code. It is commonly used to add a short explanation or note about that particular line of code.

The general syntax to write an inline comment in SQL is:

SQL statement; -- Short explanation

Example 3:

SELECT employee_name, salary -- Display employee name and salary
FROM Employees;

In this example, — Display employee name and salary is an inline comment. The SQL processor ignores the comment, while the SELECT statement is processed normally.

When Should You Use Inline Comments?

Inline comments are most useful when you need to write a short explanation directly related to a specific piece of SQL code. However, excessive inline comments can reduce readability.

Quick Comparison