MySQL Comments Explained: From Basics to Version Hints

Clear comments make SQL easier to read, debug, and maintain — especially in production environments where queries are reused or extended. MySQL supports not just ordinary comments, but also conditional “versioned” and hint-based comments for optimizer control.

This article explores all MySQL comment styles, including everyday use cases and lesser-known features that can make your scripts cleaner and more portable.

Supported Comment Styles

Single-Line Comments

-- standard comment
# also works in MySQL

Multi-Line Comments

/* comment block
   describing logic */

These are ignored during execution and won’t affect performance.

Versioned & Hint Comments

MySQL adds flexibility with executable comment syntax:

/*!80000 ALTER TABLE users ADD COLUMN last_seen DATETIME */;

This executes only if your server version is 8.0.0 or higher.

You can also use optimizer hints:

SELECT /*+ HASH_JOIN(customers, orders) */ *
FROM customers
JOIN orders ON customers.id = orders.cust_id;

Extra Examples

• Temporarily skip joins

SELECT *
FROM orders o
/* JOIN refunds r ON o.id = r.order_id */
WHERE o.status = 'completed';

• Comment inside stored procedures

DELIMITER //
CREATE PROCEDURE update_prices()
BEGIN
  /* Recalculate seasonal discounts */
  UPDATE products SET price = price * 0.95 WHERE category = 'Winter';
END //
DELIMITER ;

• Add notes to test scripts

# prepare test dataset
INSERT INTO test_data (id, name) VALUES (1, 'Sample');
-- end of test setup

Best Practices

• Use - for short context and /* */ for detailed blocks.

• Use versioned comments for backward-compatible migration scripts.

• Document intent, not execution.

• Avoid leaking configuration or sensitive details.

• Keep comments consistent with team style.

FAQ

How does commenting in MySQL work?

• -, #, and /* */ are all valid comment types. The server skips them during execution.

What are versioned comments?

Comments like /*!80000 ... */ execute only on supported versions.

Can I mix comment types?

Yes, you can combine -- and /* */ freely in scripts.

Do comments affect performance?

No, they are ignored by the query engine.

Conclusion

Commenting in MySQL is simple but powerful. Beyond regular inline notes, versioned and optimizer-aware comments let you tailor scripts to specific environments and make intent clear. The more context you add through thoughtful comments, the easier it is for others to maintain and extend your work.

For detailed examples and additional insights, read the Commenting in MySQL: Definitive Guide.