Clean SQL with Comments: Syntax and Practices for All Engines

Writing clean SQL is about more than just correctness—it's about clarity. SQL comments help you communicate with others (or your future self) by adding context, notes, or temporarily disabling code. Let’s explore how to use comments effectively.

Using Comments in SQL

Two Main Types:

• Single-line
  

  -- Pull users created in the last week
  SELECT * FROM users WHERE created_at >= CURRENT_DATE - INTERVAL '7 days';
  

• Multi-line
  

  /*
    Use this version for reporting
    Includes only verified accounts
  */
  SELECT * FROM accounts WHERE verified = TRUE;
  

Why and When to Comment

Helpful When:

• Writing complex logic
• Sharing scripts with a team
• Disabling old queries during testing

Avoid:

• Leaving sensitive info
• Explaining simple queries
• Letting comments go stale

Different Engines, Different Capabilities

• MySQL: Supports versioned comments /*! */.
• PostgreSQL: COMMENT ON lets you label schema elements.
• SQLite: Keeps it basic and portable.
• SQL Server & Oracle: Great for documenting stored code and schema.

FAQ

How do I add comments in SQL?

Use -- for quick notes or /* */ for multiple lines or blocks.

Can I use comments to remove lines during testing?

Yes—wrap code in /* */ and it won’t run.

Are comments part of SQL standards?

Yes, both styles are widely supported with small engine-specific features.

Can comments be dangerous?

Only if they include secrets or mislead developers. Keep them clean and relevant.

Conclusion

SQL comments don’t take much effort but make a big difference. They’re your best tool for writing collaborative, maintainable SQL scripts. Read SQL Comment: A Comprehensive Guide for more insights.