Comments in SQL

What Are Comments in SQL?

A long SQL query can produce the correct result and still be difficult to maintain. Six months later, a teacher, developer or database administrator may remember what the query does but not why a condition was added. A SQL comment solves that problem: it records an explanation for people while the database ignores it during normal query execution.

Good comments explain intent, business rules or unusual decisions. For example, -- Exclude students who withdrew before the exam is useful because it tells the next reader why a filter exists. A comment such as -- Select rows above a simple SELECT statement adds little value.

Comments are commonly used to document database scripts, temporarily disable a statement during testing, separate script sections and leave safety instructions before an UPDATE or DELETE query.

Three Comment Styles Supported by MySQL

MySQL supports three useful comment forms. The first two end at the current line; the third can cover part of a line or several lines.

1. Double hyphen: --

-- Show active students only
SELECT roll_no, name
FROM students
WHERE status = 'Active';

Important MySQL rule: place whitespace after the two hyphens. Write -- explanation, not --explanation. This rule prevents arithmetic expressions such as credit--1 from being misread.

2. Hash sign: #

# Monthly fee report for Class XII
SELECT student_id, amount
FROM fee_payments
WHERE payment_month = 'August';

The hash form is convenient in MySQL, but it is not part of standard SQL. Prefer -- when a script may later move to PostgreSQL, SQL Server, Oracle or another database.

3. Block comment: /* ... */

/* Annual result report
   Prepared for Classes IX to XII
   Reviewed on 14 August 2026 */
SELECT class_name, AVG(percentage) AS class_average
FROM results
GROUP BY class_name;

A block comment begins with /* and ends with */. It is suitable for a file header, a detailed explanation or a short inline note. Do not nest one block comment inside another; the first closing marker may end the comment earlier than expected.

Working SQL Comment Examples with Output

The following examples use a small school table so that you can run every query and verify the result.

CREATE TABLE students (
    roll_no INT PRIMARY KEY,
    name VARCHAR(50),
    class_name VARCHAR(10),
    status VARCHAR(10)
);

INSERT INTO students VALUES
(1, 'Aarav', 'X-A', 'Active'),
(2, 'Meera', 'X-A', 'Active'),
(3, 'Kabir', 'X-B', 'Inactive');

Example 1: A comment on its own line

-- Only currently enrolled students appear in the report
SELECT roll_no, name
FROM students
WHERE status = 'Active'
ORDER BY roll_no;

The sentence beginning with -- is ignored. The WHERE condition, not the comment, removes Kabir from the result.

Example 2: An inline block comment

SELECT name, /* shown on the ID card */ class_name
FROM students
WHERE roll_no = 2;

Because /* ... */ can appear between SQL tokens, it documents one selected column without disabling the remaining statement.

Example 3: Temporarily disable one condition

SELECT roll_no, name, class_name
FROM students
WHERE status = 'Active'
/* AND class_name = 'X-A' */
ORDER BY roll_no;

The class filter is temporarily ignored while the active-status filter still runs. This is useful during debugging, but remove obsolete commented-out code before a production release.

SQL Comment Syntax Compared

Practical Uses and Best Practices

• Explain the reason: write why a filter, join or calculation is required, especially when the reason is not obvious.
• Record assumptions: note whether marks exclude absentees, fees include late charges or dates use a specific time zone.
• Mark safe execution: before changing data, remind the reader to run the matching SELECT first and confirm the target rows.
• Separate a long script: clear headings such as -- 1. Create tables and -- 2. Insert master data improve navigation.
• Keep comments current: an outdated comment is more dangerous than no comment because it gives false confidence.
• Never store secrets: passwords, API keys and personal student data do not belong in comments; scripts may be shared or committed to Git.

When documenting a data-changing query, also follow the safeguards explained in Safe UPDATE and DELETE Practices.

Common Mistakes While Commenting in MySQL

• Missing whitespace after --: --wrong may not start a MySQL comment. Use -- correct explanation.
• Expecting a line comment to continue: both -- and # stop at the newline. Add a marker on every line or use a block comment.
• Forgetting */: an unfinished block comment can hide the rest of the script or produce a syntax error.
• Nesting block comments: MySQL does not safely support arbitrary nested /* ... */ comments.
• Using # in portable SQL: another DBMS may reject the file. Use the standard double-hyphen form.
• Writing what the code already says: explain the rule or decision instead of translating every SQL keyword into English.

Practice Questions

1. Write a single-line comment that explains why inactive students are excluded from a report.
2. Temporarily disable AND city = 'Khurja' without deleting it.
3. Explain why --comment is unsafe in MySQL but -- comment is correct.
4. Which comment form would you choose for a script shared across different database systems, and why?

Quick Summary

• SQL comments document a query but are normally ignored during execution.
• -- is the preferred portable single-line syntax; include whitespace after the hyphens in MySQL.
• # is a MySQL-specific single-line comment.
• /* ... */ creates an inline or multi-line block comment.
• Useful comments explain intent, rules and risks; they do not repeat obvious SQL.
• Keep comments accurate and never place passwords or sensitive data inside them.

Official References

• Comments — MySQL 8.4 Reference Manual
• Optimizer hints inside comments — MySQL 8.4 Reference Manual
• MySQL 8.4 Reference Manual

References reviewed on 14 August 2026. Queries, outputs and explanations are original teaching material.