LearnSQL Comments: Single-Line (--), Multi-Line (/* */) & Query Hints

8 / 61 0%

Lesson 08 of 61

5 mins read

SQL Comments: Single-Line (--), Multi-Line (/* */) & Query Hints

In Plain English

Comments explain business logic, document complex joins, and temporarily disable clauses during query debugging. Standard SQL supports single-line comments starting with `--` and multi-line block comments enclosed between `/*` and `*/`.

The Mental Model

"Comments are like sticky notes left on a blueprint: they guide future developers and maintenance engineers without altering the physical building structure."

Deep Dive: How It Works

Single-Line Comments: `-- This is ignored until the end of the line`.

Multi-Line Block Comments: `/* Multi-line explanation or disabled code block */`.

Optimizer Query Hints: In database engines like MySQL (`/*+ INDEX(users idx_email) */`) and Oracle, special comment blocks provide execution directives to the query planner.

Syntax Blueprint

-- Single line comment
SELECT id, name /* inline comment */
FROM users
/* Multi-line
   documentation block */
WHERE active = 1;

Use -- for quick notes and /* */ for multi-line documentation.

Core Rules to Remember

Ignored by Engine: Comments have zero execution overhead and are skipped by SQL parsers.

Clause Toggling: Quickly comment out WHERE conditions (`-- AND status = 'active'`) during testing.

Migration Scripts: Document the rationale and ticket reference for schema migrations.

Common Beginner Traps & How to Fix Them

Mistake:Accidentally leaving a `--` comment inside a dynamic SQL string without a trailing newline before the next clause.

Why it happens: The remainder of the dynamic query gets commented out on the same line.

How to fix: Ensure newlines separate query lines when generating SQL programmatically.

Pro Tip: Use block comments `/* ... */` to document complex SQL views and stored procedures directly inside the database schema repository.

Live Interactive Example

Hit Run Code to see it live

Documenting Queries with Comments

Python 3.12

Output Console

Click "Run Code" to view the rendered output.

How it works: All single-line and multi-line comments were cleanly parsed and ignored during execution.

Your Turn: Micro Challenge

No pressure! Edit the starter code below and test your solution with instant feedback.

Micro Exercise

Write a Query with Comments

Add a single-line comment `-- Query active users` and run `SELECT name FROM clients;`.

Sandbox Output

Click "Run & Check" to test your solution.

Finished reading and practicing?

Mark this lesson as completed to update your course progress.