SQL Comments

💬 SQL Comments are non-executable lines of text used to explain SQL code, improve readability, and document database scripts. Comments are ignored by the SQL parser during execution, making them useful for adding notes without affecting the behavior of SQL statements.

📖 What are SQL Comments?

SQL comments help developers understand the purpose of queries, tables, columns, and business logic. They are commonly used to document complex SQL statements, temporarily disable code during testing, and improve collaboration among team members.

Information

Comments are intended for humans, not the database engine. They do not affect the execution of SQL statements.

📝 Types of SQL Comments

SQL supports two main types of comments:

  • ➡️ Single-line comments
  • ➡️ Multi-line (block) comments

1️⃣ Single-Line Comments

A single-line comment begins with --. Everything after -- on the same line is treated as a comment.

Single-Line Comment

-- Retrieve all student records
SELECT * FROM Students;

You can also place a single-line comment after an SQL statement.

Comment After a Statement

SELECT * FROM Students; -- Display all students

2️⃣ Multi-Line (Block) Comments

Multi-line comments begin with /* and end with */. They are useful for writing longer explanations or commenting out multiple lines of SQL code.

Multi-Line Comment

/*
  This query retrieves all students
  from the Computer Science department.
*/
SELECT *
FROM Students
WHERE Department = 'Computer Science';

💡 Why Use SQL Comments?

  • 📚 Explain the purpose of SQL queries.
  • 👥 Improve collaboration within development teams.
  • 🛠️ Make complex SQL scripts easier to understand.
  • 🧪 Temporarily disable queries during testing.
  • 📖 Document business rules and database logic.

🧪 Commenting Out SQL Code

During development, comments can be used to temporarily disable SQL statements without deleting them.

Disable a Query

-- DELETE FROM Students
-- WHERE StudentID = 101;

SELECT * FROM Students;

You can also comment out multiple lines using a block comment.

Disable Multiple Statements

/*
UPDATE Students
SET Department = 'Information Technology'
WHERE StudentID = 101;

DELETE FROM Students
WHERE StudentID = 102;
*/

📊 Comparison of SQL Comment Types

Comment TypeSyntaxBest Used For
Single-Line -- CommentShort notes or explanations.
Multi-Line /* Comment */Detailed documentation or multiple lines.

💼 Real-World Example

Documented SQL Query

-- Retrieve active employees ordered by name
SELECT EmployeeID,
       FullName,
       Department
FROM Employees
WHERE IsActive = TRUE
ORDER BY FullName ASC;

The comment clearly explains what the query does before the SQL statement begins, making the script easier to maintain.

⚠️ Best Practices

Best Practice

Write clear and concise comments, keep them up to date when the SQL code changes, avoid stating the obvious, and use comments to explain why a query exists rather than simply describing what the SQL syntax already shows.

🚫 Common Mistakes

MistakeWhy It's a ProblemRecommendation
Outdated commentsThey can mislead developers.Update comments whenever code changes.
Too many unnecessary commentsThey reduce readability.Comment only where additional explanation is helpful.
Using comments to hide unused code permanentlyMakes scripts cluttered.Remove obsolete code after testing.

🚀 Key Points to Remember

  • 📌 SQL comments are ignored during execution.
  • 📌 Use -- for single-line comments.
  • 📌 Use /* ... */ for multi-line comments.
  • 📌 Comments improve readability and maintainability.
  • 📌 Keep comments accurate and relevant.
>>"Good comments don't replace clean SQL—they explain the intent behind it."

Summary

✅ SQL comments are an essential documentation tool that helps developers write readable, maintainable, and collaborative database scripts. By using both single-line and multi-line comments appropriately, you can make SQL code easier to understand without affecting its execution.