Introduction

Comments in MySQL help explain intent, migration risk, and schema meaning when they are used carefully. MySQL supports both SQL text comments and persistent metadata comments on tables and columns. Good comment strategy improves maintainability without turning SQL scripts into stale documentation.

SQL Text Comment Syntax in MySQL

MySQL supports three common inline styles:

• Double-hyphen single-line comment.
• Hash single-line comment.
• Block comment between slash and star markers.

1-- Single-line comment with required space after dashes
2SELECT 1;
3
4# Alternative single-line comment style
5SELECT 2;
6
7/* Multi-line
8   comment block */
9SELECT 3;

The double-hyphen form should include a following space for parser clarity and portability.

Write Comments for Intent, Not Obvious Syntax

Useful comments explain business constraints or non-obvious choices.

1/* Business rule: suspended accounts are excluded from payout processing */
2SELECT account_id, amount
3FROM payouts
4WHERE status = 'READY'
5  AND suspended = 0;

A comment that repeats SQL syntax adds noise and quickly becomes stale.

Persistent Schema Comments

If documentation should live with schema objects, use COMMENT clauses in DDL.

1CREATE TABLE orders (
2    id BIGINT PRIMARY KEY,
3    customer_id BIGINT NOT NULL COMMENT 'foreign key to customers.id',
4    amount DECIMAL(12,2) NOT NULL COMMENT 'order total in USD',
5    created_at TIMESTAMP NOT NULL
6) COMMENT='Customer order records';

These comments are queryable through metadata views and survive beyond one migration script.

Update column comments later with alter statement:

ALTER TABLE orders
MODIFY COLUMN amount DECIMAL(12,2) NOT NULL COMMENT 'total charged amount in USD';

Version-Specific Comments

MySQL also supports version-gated execution comments for compatibility.

SELECT /*!80000 JSON_PRETTY(payload) */ payload
FROM audit_events;

Only compatible MySQL versions execute the embedded SQL. Use this sparingly, because heavy use can reduce script readability.

Stored Procedure and Migration Script Practices

Procedural code benefits from concise phase markers.

1DELIMITER //
2
3CREATE PROCEDURE archive_old_sessions()
4BEGIN
5    -- Delete sessions beyond retention window
6    DELETE FROM sessions
7    WHERE last_seen < NOW() - INTERVAL 90 DAY;
8
9    /* Audit maintenance execution */
10    INSERT INTO maintenance_log(task_name, executed_at)
11    VALUES ('archive_old_sessions', NOW());
12END //
13
14DELIMITER ;

Migration headers are also useful:

1/*
2  migration: V20260305_01
3  purpose: add composite index for invoice lookup
4*/
5ALTER TABLE invoices
6ADD INDEX idx_invoices_customer_date(customer_id, invoice_date);

Short and structured headers improve review speed.

Toolchain and Formatting Considerations

Some SQL formatters or migration tools modify or remove comments. Before treating comments as critical documentation, verify your pipeline preserves them.

Practical checks:

• Run formatter and inspect output.
• Validate migration artifact in CI.
• Confirm schema comments persist after deployment.

If comments are stripped, keep critical operational documentation in dedicated runbooks.

Security and Compliance Notes

Do not place secrets, credentials, or sensitive incident details in SQL comments. Scripts often move across repositories, logs, or deployment artifacts.

Safer approach:

• Keep comments technical and non-sensitive.
• Put confidential context in secured documentation systems.
• Include comment review in migration code review checklist.

Team Commenting Guidelines

A simple convention keeps quality high:

1. Comment only non-obvious intent.
2. Remove comments when logic changes.
3. Prefer schema comments for durable data dictionary notes.
4. Avoid leaving commented-out dead SQL in long-lived scripts.

Comment hygiene should be maintained continuously, not during occasional cleanup drives.

Common Pitfalls

• Using double-hyphen comments without required spacing.
• Leaving outdated comments after query refactors.
• Using comments as substitute for proper migration history.
• Storing sensitive details in widely distributed SQL files.
• Assuming tooling preserves comments without verification.

Summary

• MySQL supports line and block comments for SQL text annotation.
• Use comments to explain intent and constraints, not obvious syntax.
• Use COMMENT clauses for persistent schema documentation.
• Apply version-gated comments only where compatibility requires them.
• Keep comments current, concise, and safe for broad visibility.