Part 2: Mastering SQL Comments | SQL Challenges & Capstone
SQL Business Logic & Data Handling Practice · Part 2 · Lecture Notes
Mastering SQL Comments
How to document SQL queries using single-line and multi-line comments — explaining business logic, improving readability, and supporting team collaboration.
Part 2 of 633% Complete
— Single-Line
/* Multi-Line */
Query Documentation
Business Rules
8 Practice Questions
Learning Objectives
Write single-line comments using — to annotate individual lines of SQL
Write multi-line comments using /* */ to document larger sections of query logic
Use comments to explain the business purpose of a query and the reasoning behind filters
Understand that comments are completely ignored when SQL executes — they only serve human readers
Click any section header to open or close it
SQL comments allow analysts to add notes and explanations inside SQL queries. Comments are completely ignored by the database when the query executes — they exist only for humans reading the code. Well-commented SQL is easier to maintain, easier to hand off to colleagues, and easier to return to weeks or months later.
In industry, analysts use comments to explain SQL logic, document business rules behind filters and calculations, improve team collaboration, organize complex multi-step queries, and make reports easier to understand for non-technical reviewers.
Two Types of SQL Comments
Single-line comments begin with — (two hyphens) and apply to the rest of that line only. Multi-line comments are wrapped in /* and */ and can span as many lines as needed. Both types are completely ignored when SQL runs.
Single-line comments start with two hyphens (–) and extend to the end of the current line. Everything after — on that line is treated as a comment. Single-line comments are best for short explanations — describing what a WHERE condition does, why a specific value was chosen, or what a query is for.
When to Use Single-Line Comments
Use — for brief annotations: explaining a WHERE condition, labelling a SELECT column, or giving the query a one-line purpose statement at the top. If the explanation needs more than one line, switch to a multi-line comment.
Single-Line Comment — Query Purpose
— Show all users from Canada
SELECT *
FROM users
WHERE country = ‘Canada’;
Inline Comment — Explaining a Calculation
SELECT
transaction_id,
— Round transaction amount to 2 decimal places
ROUND(amount, 2) AS amount
FROM transactions;
Multi-line comments open with /* and close with */ and can contain any number of lines in between. They are best for longer explanations — describing the business purpose of a query, documenting a set of filtering conditions, or providing context that a single line cannot capture.
When to Use Multi-Line Comments
Use /* */ when the explanation runs to two or more lines, when documenting the business context of a query, or when temporarily disabling a block of SQL during testing. Everything between /* and */ is ignored by the database.
Multi-Line Comment — Business Context
/*
Retrieve high-value transactions
for financial review
*/
SELECT *
FROM transactions
WHERE amount > 100;
In professional environments, SQL queries are shared, reviewed, and maintained by multiple people. Comments turn a query from a set of cryptic commands into documented, self-explanatory code. A colleague reading a well-commented query understands not just what it does but why it was written that way.
Professional Documentation Standard
At minimum, professional SQL queries include: a comment at the top explaining the business purpose, comments on any non-obvious WHERE conditions, and inline comments on complex calculations. This is the standard in analytics teams and BI departments.
Documented Query — Active Subscriptions
— Retrieve active subscriptions only
SELECT *
FROM subscriptions
WHERE status = ‘Active’;
Work through each question below. Run your query first, then use Check Answer. A wrong answer reveals the correct SQL with a Copy button; a correct result earns a congratulations message.
Practice 1Add a single-line comment explaining a query that retrieves all users
AI Prompt
Write a MySQL query with a single-line comment explaining a query that retrieves all users.
SQL Answer
— Retrieve all users
SELECT *
FROM users;
Practice 2Add a multi-line comment explaining a query that retrieves transactions above 50 dollars rounded to 2 decimal places
AI Prompt
Write a MySQL query with a multi-line comment explaining a query that retrieves transactions above 50 dollars rounded to 2 decimal places.
SQL Answer
/*
Retrieve transactions
greater than 50 dollars
*/
SELECT
transaction_id,
ROUND(amount, 2) AS amount
FROM transactions
WHERE amount > 50;
Practice 3Add a single-line comment explaining a query that retrieves all products
AI Prompt
Write a MySQL query with a single-line comment explaining a query that retrieves all products.
SQL Answer
— Retrieve all products
SELECT *
FROM products;
Practice 4Add a multi-line comment explaining a query that retrieves completed orders
AI Prompt
Write a MySQL query with a multi-line comment explaining a query that retrieves completed orders.
SQL Answer
/*
Retrieve completed
customer orders
*/
SELECT *
FROM orders
WHERE order_status = ‘Completed’;
Practice 5Add a comment explaining a query that retrieves active subscriptions
AI Prompt
Write a MySQL query with a comment explaining a query that retrieves active subscriptions.
SQL Answer
— Retrieve active subscriptions
SELECT *
FROM subscriptions
WHERE status = ‘Active’;
Practice 6Add a comment explaining a query that retrieves open support tickets
AI Prompt
Write a MySQL query with a comment explaining a query that retrieves open support tickets.
SQL Answer
— Retrieve open support tickets
SELECT *
FROM support_tickets
WHERE ticket_status = ‘Open’;
Practice 7Add a multi-line comment explaining a query that retrieves campaigns using Email channels
AI Prompt
Write a MySQL query with a multi-line comment explaining a query that retrieves campaigns using Email channels.
SQL Answer
/*
Retrieve campaigns
using Email channels
*/
SELECT *
FROM campaigns
WHERE channel = ‘Email’;
Practice 8Add a comment explaining a query that retrieves sessions from Mobile devices
AI Prompt
Write a MySQL query with a comment explaining a query that retrieves sessions from Mobile devices.
SQL Answer
— Retrieve sessions from Mobile devices
SELECT *
FROM sessions
WHERE device_type = ‘Mobile’;
Knowledge Check
Five questions — select the best answer for each.
1. What happens when SQL runs a query that contains comments?
AThe comment text is displayed as an extra row in the results
BComments cause a syntax error
CComments are completely ignored — only the SQL code executes
DComments slow down query performance
Correct. SQL comments are invisible to the database engine. When the query runs, comment text is stripped out before execution — only the actual SQL commands are processed.
Not quite. Comments are completely ignored when SQL runs — they exist only for human readers and have no effect on execution.
2. Which symbol starts a single-line SQL comment?
A//
B#
C/*
D—
Correct. In SQL, — (two hyphens) starts a single-line comment. Everything after — on that line is ignored. Note: MySQL also supports # for single-line comments, but — is the SQL standard.
Not quite. In standard SQL, — (two hyphens) starts a single-line comment. Everything on the same line after — is ignored.
3. Which syntax correctly wraps a multi-line SQL comment?
A// comment text //
B/* comment text */
C— comment text —
D** comment text **
Correct. Multi-line comments in SQL open with /* and close with */. Everything between these markers — on any number of lines — is treated as a comment.
Not quite. Multi-line SQL comments use /* to open and */ to close: /* your comment here */
4. Why do professional analysts add comments to SQL queries?
ATo make queries run faster
BTo filter out unwanted rows
CTo explain logic, document business rules, and support collaboration
DTo prevent other users from editing the query
Correct. Comments document the purpose and reasoning behind SQL code — making queries maintainable, shareable, and understandable by colleagues who didn’t write them.
Not quite. Comments document logic and business rules — making queries easier to understand, maintain, and share with colleagues.
5. An analyst writes — Retrieve active subscriptions before a WHERE clause. What effect does this have on the query result?
AThe query only returns subscriptions labelled active in the comment
BNo effect — the comment is ignored and the WHERE clause still filters normally
CThe comment replaces the WHERE clause
DThe query returns an error because comments cannot appear before WHERE
Correct. Comments have zero effect on query logic or results. The WHERE clause still applies normally — the comment is purely for documentation.
Not quite. Comments have no effect on query execution. The WHERE clause still runs normally; the comment is invisible to the database.
Part 2 Summary
The key ideas from this lecture — keep these in mind as you move forward.
SQL comments help analysts document query logic, explain business rules, and improve collaboration and readability. Use — for single-line notes. Use /* */ for multi-line documentation. Comments are invisible to the database and have no effect on query results.
