Comments in SQL: Best Practices

We’ve all been there: looking at a cryptic SQL query from six months ago, wondering what on Earth it was supposed to do. You might think, “Who wrote this monstrosity?”—only to realize it was you. Welcome to the hidden value of good comments in SQL!

TL;DR

Comments make your SQL code easier to understand and maintain.
They help both you and your team remember why you wrote a query in a certain way.
Use clear, concise comments. Prefer full-line comments over inline when possible.
Don’t comment every line—only what’s complex, tricky, or not obvious.

Why Comment at All?

SQL is powerful—but not always readable. Especially when:

You use complex joins
You write nested subqueries
You manipulate dates and strings

Your future self will thank you for leaving clues. So will your teammates!

Types of SQL Comments

In SQL, there are two main ways to write comments:

Single-line comments – Use --
Multi-line comments – Use /* your comment */

Examples:

-- This is a single-line comment
SELECT * FROM employees;

/*
  This is a multi-line comment.
  Use it when explaining something more complex.
*/
SELECT *
FROM employees
WHERE salary > 50000;

Best Practices for SQL Comments

1. Comment to Explain ‘Why’, Not ‘What’

SQL is readable. Anyone can see what a query does. But they may not know why you wrote it that way.

-- Filtering out interns because they don't need full access
SELECT * FROM employees WHERE role != 'intern';

Don’t say:

-- Select all employees that are not interns
SELECT * FROM employees WHERE role != 'intern';

We can already see that from the code!

2. Keep Comments Short and Sweet

Be clear. Pretend you’re writing for someone reading your code in a rush.

-- Business rule: Sales team bonuses are calculated differently
SELECT * FROM bonuses WHERE department = 'Sales';

3. Use Comments to Mark Sections

Long queries benefit from section dividers. It helps navigation.

-- Step 1: Get active customers
-- Step 2: Join with recent orders
-- Step 3: Calculate lifetime value

This structure turns a spaghetti query into a readable meal.

4. Avoid Inline Comments (Most of the Time)

Inline comments sit at the end of a line. They can clutter things up.

SELECT name, birthdate FROM users -- Get user info

Instead, place comments above the line. It’s cleaner:

-- Get user info
SELECT name, birthdate FROM users;

However, inline comments can be useful in specific cases:

SELECT 
  cost * 0.8 AS discounted_cost -- 20% discount
FROM products;

Use with care!

5. Don’t Go Overboard

Too many comments can be as bad as none. Keep it useful. Comment things that:

Are hard to understand
Contain business logic
Might need debugging later

Don’t comment every single line. Trust your reader a little.

Real-Life Example

Let’s turn a messy query into a well-commented one.

Before:

SELECT c.name, COUNT(o.id)
FROM customers c
JOIN orders o ON c.id = o.customer_id
WHERE o.date >= CURRENT_DATE - INTERVAL '30 days'
GROUP BY c.name
ORDER BY COUNT(o.id) DESC;

Better:

-- Get top customers based on recent orders
SELECT 
  c.name, 
  COUNT(o.id) AS recent_orders
FROM customers c

-- Join with orders table
JOIN orders o 
  ON c.id = o.customer_id

-- Only include orders from the last 30 days
WHERE o.date >= CURRENT_DATE - INTERVAL '30 days'

GROUP BY c.name
ORDER BY recent_orders DESC;

Now, even someone new can understand the logic.

Commenting in Stored Procedures

Stored procedures often contain logic flows. Great commenting is key here.

-- Stored procedure to update shipping status
CREATE PROCEDURE update_shipping_status()
BEGIN
  -- Step 1: Update status for shipped orders
  UPDATE orders
  SET status = 'Shipped'
  WHERE shipped_date IS NOT NULL;

  -- Step 2: Notify customers
  CALL notify_customers();
END;

Without comments, figuring this out could take much longer—even for simple tasks.

When to Delete Old Comments

Comments are great, but stale ones cause confusion. If the code changes, and the comment doesn’t—it’s worse than no comment.

Golden rule: When you change your code, update the comment.

If you see a comment like:

-- This query excludes archived users
SELECT * FROM users;

But the actual query doesn’t exclude archived users… uh oh! That’s misleading.

Use Comments During Debugging (Then Remove Them)

When debugging, it’s normal to add comments to skip parts of a query:

-- Debugging: Removing WHERE clause temporarily
-- WHERE status = 'active'

Just don’t forget to clean these up later. Spoiler: Someone will copy your test query and run it in production.

Use Comment Syntax Correctly

Remember that syntax can vary slightly depending on your SQL flavor:

MySQL, PostgreSQL: Use -- or /* */
SQL Server: Same as above
SQLite: Only supports --

Always test your comments in your specific database to avoid errors.

Commenting Tools and Extras

Got a huge SQL file? Use editors like:

SQL Server Management Studio
DBeaver
DataGrip

They let you comment/uncomment blocks quickly.

You can also add TODO and FIXME notes in comments:

-- TODO: Optimize join with transactions
-- FIXME: Possible duplicate IDs showing up

These make your intentions clear to other developers.

Final Thoughts

SQL comments are like notes in the margin of your favorite book. They don’t change the plot—but they make the story easier to follow.

Good comments = less confusion = happier team. So next time you write a query, take a few seconds to leave breadcrumbs for the next person (or yourself!).

Because nothing haunts developers like their own undocumented SQL.

sql developer, thinking, messy code[/ai-img>

WP Sticky