SQL COMMENTS – Write Clear and Maintainable SQL Code
Introduction – Why Use Comments in SQL?
SQL comments allow you to annotate your queries and scripts with helpful explanations, descriptions, or reminders. They improve readability, maintainability, and team collaboration.
In this guide, you’ll learn:
- Syntax for single-line and multi-line comments
- Platform-specific behavior
- Best practices for writing clean and meaningful comments
🗒️ 1. Single-Line Comments
-- This is a single-line comment
SELECT * FROM users; -- Get all user records
Use -- to mark a comment until the end of the line.
2. Multi-Line Comments
/*
This is a multi-line comment.
It can span multiple lines of explanation.
*/
SELECT * FROM orders;
Use /* */ to wrap multiple lines of comment.
3. Database-Specific Notes
| Database | Single-Line | Multi-Line |
|---|---|---|
| MySQL | --, # | /* */ |
| PostgreSQL | -- | /* */ |
| SQL Server | -- | /* */ |
| Oracle | -- | /* */ |
Most systems support both styles. # is MySQL-only.
4. Comment Use Cases
| Scenario | Example |
|---|---|
| Disable a query temporarily | -- SELECT * FROM logs; |
| Describe logic or joins | -- Joining orders with customers |
| Label sections of a script | /* Step 1: Load staging data */ |
| Clarify filter conditions | -- Exclude inactive users from the result |
Best Practices
| Recommended | Avoid This |
|---|---|
| Use comments to explain why, not just what | Leaving code without context |
| Update comments as queries evolve | Letting them become misleading |
| Keep comments brief and relevant | Writing essays in SQL comments |
Summary – Recap & Next Steps
SQL comments are essential for code quality, collaboration, and long-term maintenance. They guide developers, clarify purpose, and help avoid confusion.
Key Takeaways:
- Use
--for single-line and/* */for block comments - Supported by all major RDBMS with minor variations
- Use comments to improve code readability and manage complex logic
Real-World Relevance:
Used in schema scripts, stored procedures, analytics reports, and CI/CD SQL deployments.
FAQ – SQL Comments
Can I comment out part of a SQL query?
Yes. You can disable code using -- or /* ... */.
Are comments stored in the database?
No. They’re ignored during parsing and not stored in the execution plan.
Can comments cause SQL errors?
Rarely. Only if used inside strings or misplaced syntax.
Share Now :
