How to Use SQL Comments Effectively: Syntax, Engines, and Best Practices

Writing SQL that others can understand is just as important as writing code that works. SQL comments help you explain queries, disable parts of your code, and document your logic. This post gives you a focused look at SQL comment syntax, practical use cases, and differences across major databases.

Core Usage of SQL Comments

Basic Syntax

• Single-line

    -- Select active customers
    SELECT * FROM customers WHERE status = 'active';
  

• Multi-line

    /*
      This block disables a test query
      while debugging other issues
    */
    -- SELECT * FROM debug_data;
  

Pros of Commenting

• Improves clarity for teammates and future revisions.

• Useful for debugging by disabling parts of a query.

• Great for leaving context during data migrations.

What to Avoid

• Writing outdated notes.

• Over-commenting obvious code.

• Including API keys, user credentials, or internal logic.

SQL Engine Overview

• MySQL: Supports standard formats and versioned comments (e.g., /*! SQL */).

• PostgreSQL: Use COMMENT ON for schema documentation.

• SQLite: Simple support; ideal for lightweight applications.

• SQL Server: Comments widely used in functions and procedures.

• Oracle: Rich comment support, including PL/SQL blocks.

FAQ

What’s the difference between - and /* */?

• - is for single lines; /* */ is for longer or multiline notes.

Can I disable a query temporarily with a comment?

Yes. Use /* */ to wrap the query or line you want to ignore.

Is it bad to comment too much?

Yes—comments should explain intent, not repeat what the code already shows. Use them where they add value.

Are comments visible in query logs?

In some environments, yes. Be careful not to expose sensitive data.

Conclusion

Use SQL comments wisely to improve collaboration, clarity, and debugging. Different engines have their quirks, but the fundamentals are universal.

Read SQL Comment: A Comprehensive Guide for deeper coverage and best practices.