SQL Comment Tutorial – Quick Guide

1. What Are SQL Comments?

SQL comments are non-executable lines of text added to SQL code to explain its purpose, logic, or structure. They are ignored by database engines during query execution but serve as valuable notes for developers, making code easier to understand and maintain.

Comments help document complex queries, provide context for future modifications, and assist in debugging by temporarily disabling parts of SQL code without deletion. They are especially useful in team environments where multiple developers work on the same database scripts.

Unlike regular SQL commands, comments do not affect performance or database operations. They exist purely for human readability, ensuring that SQL remains clear, organized, and well-documented. Whether you're writing simple queries or complex stored procedures, proper commenting is a best practice in database development.

2. Types of SQL Comments

SQL supports two main types of comments, each serving different purposes in query writing and documentation:

Single-Line Comments

These comments span only one line and are ideal for quick notes or brief explanations. They begin with -- (two hyphens) and continue until the end of the line. For example:

-- This query retrieves all active users
SELECT * FROM users WHERE status = 'active';

Single-line comments are widely supported across all major database systems, including MySQL, PostgreSQL, SQL Server, and Oracle.

Multi-Line Comments

Also known as block comments, these allow for longer explanations or temporarily disabling multiple lines of SQL code. They start with /* and end with */. For example:

/*
  This query fetches:  
  - User details  
  - Their latest order  
  For the monthly sales report  
*/
SELECT u.name, o.order_date 
FROM users u 
JOIN orders o ON u.id = o.user_id;

Multi-line comments are useful for documenting complex queries, providing detailed instructions, or "commenting out" sections of code during testing.

Key Differences & Usage Tips

• Single-line comments are best for short notes, while multi-line comments work well for longer documentation.

• Some databases (like MySQL) also support # for single-line comments, but -- is more universally compatible.

• Avoid over-commenting simple queries—use them where clarification is truly needed.

3. How to Use SQL Comments Effectively

Now that we've covered the types of SQL comments, let's explore best practices for using them to write cleaner, more maintainable code.

When to Comment SQL Code

1. Explain Complex Logic

   • Use comments to clarify intricate joins, subqueries, or business rules that aren't immediately obvious.

     -- Calculate lifetime value for VIP customers (purchases > $1000)
     SELECT customer_id, SUM(amount) AS lifetime_value
     FROM orders
     WHERE customer_id IN (
         SELECT customer_id FROM vip_customers  -- Subquery identifies VIPs
     )
     GROUP BY customer_id;

2. Mark Temporary Code Changes

   • Comment out clauses for debugging without deleting them:

     SELECT product_name, price
     FROM products
     WHERE category = 'electronics'
     -- AND discount_price IS NOT NULL  (disabled for testing)

3. Document Stored Procedures & Functions

   • Add a header block to explain purpose, parameters, and usage:

     /*
     * sp_get_customer_orders  
     * Fetches order history + total spend for a customer  
     * @customer_id INT - ID of target customer  
     * Returns: Order details with subtotals  
     */

Commenting Mistakes to Avoid

• Don't state the obvious

  -- Selects all columns from users  (redundant)
  SELECT * FROM users;

• Don't leave outdated comments – Update or remove them when modifying code.

• Avoid excessive commenting – Well-written SQL often self-documents through clear table/column names.

Advanced Tip: Conditional Comments

Some databases (like MySQL) support execution-based comments for compatibility:

/*! SELECT * FROM users */  -- Executes only in MySQL