Commenting in SQL Scripts

Comments are one of the most overlooked but most important parts of writing maintainable SQL. A well-commented script tells future readers — including yourself six months from now — why a query was written a certain way, what a stored procedure does, and which blocks of code can be safely disabled. This chapter covers all three MySQL comment styles, when to use each, and professional commenting conventions.

Why Comments Matter in SQL

Unlike application code, SQL scripts often run directly on live data. A single misunderstood statement can delete thousands of rows or change critical business records. Comments serve as the safety net — documenting intent, flagging dangerous operations, and explaining business logic that isn’t obvious from the query alone.

📖 Documentation
Explain what a query does, what tables it affects, and what business rule it implements.
🔧 Debugging
Temporarily disable parts of a query to isolate problems without deleting code.
⚠️ Safety Warnings
Flag destructive operations, remind yourself to add a WHERE clause, or note that a script is irreversible.
📅 Change History
Note who wrote a script, when it was last modified, and why changes were made.
🏷️ Section Headers
Organise long migration scripts or stored procedures into clearly labelled sections.
🔗 Version Markers
Indicate which MySQL version a feature requires, or note when an approach was deprecated.

The Three Comment Styles in MySQL

MySQL supports three distinct comment syntaxes — two inherited from SQL standards, and one unique to MySQL:

Style 1 — Double Dash
— your comment here
The standard ANSI SQL single-line comment. Everything from -- to the end of the line is ignored by MySQL.
⚠️ MySQL requires at least one space after the two dashes. --comment (no space) is NOT treated as a comment.
Style 2 — Hash
# your comment here
MySQL-specific single-line comment using the hash/pound symbol. Everything from # to end of line is ignored.
Works in MySQL but not in standard SQL (PostgreSQL, Oracle, SQL Server). Use -- for portable scripts.
Style 3 — Block Comment
/* your comment here */
Multi-line / block comment. Everything between /* and */ is ignored. Can span multiple lines or sit inline within a statement.
Standard C-style syntax. Supported in all major SQL databases. The only style that works mid-statement.

Comment Syntax — Detailed Examples

SQL — All Three Comment Styles 
1-- This is a single-line comment using double-dash (ANSI standard)
2-- A space AFTER the dashes is required in MySQL
3
4SELECT * FROM customers;  -- inline comment: retrieves all customers
5
6# This is a hash-style comment (MySQL only, not portable)
7SELECT * FROM products;  # inline hash comment also works
8
9/*
   This is a block comment.
   It can span as many lines as needed.
   Great for long explanations or disabling large code blocks.
*/
14SELECT product_name, price FROM products;
15
16-- Block comment inline within a SELECT statement
17SELECT first_name, /* last_name, */ email
18FROM   customers;
19-- Only first_name and email are returned; last_name is commented out

⚠️ The space after -- matters. MySQL requires a space (or a newline) after the double dash. This is intentional — it prevents SQL expressions like 5--1 (which means “5 minus negative 1” mathematically) from being accidentally interpreted as a comment. Always write -- with a trailing space.

Using Comments to Disable Code

One of the most valuable comment use cases is temporarily disabling SQL code during development and testing — without deleting it. This is especially useful when debugging complex queries or migration scripts.

SQL — Commenting Out Code for Debugging 
1-- Testing UPDATE without the WHERE clause first — disabled for safety
2/*
UPDATE products
SET    price = price * 1.10;
*/
6
7-- Safe version with WHERE clause — only this runs
8UPDATE products
9SET   price = price * 1.10
10WHERE category = 'Electronics';
11
12-- Commenting out a JOIN to debug step by step
13SELECT c.first_name, c.email,
14       o.order_id   -- , o.total_amount (disabled during debug)
15FROM   customers c
16JOIN   orders o ON c.customer_id = o.customer_id;

Pro tip: When commenting out a dangerous operation like DROP TABLE or a DELETE without a WHERE, always add a comment explaining why it’s disabled — so the next person who reads the script understands it’s intentionally inactive, not accidentally forgotten.

Professional Script Header — A Real-World Template

In production environments, every SQL script file should begin with a header block comment that documents its purpose, author, version, and any critical warnings. Here’s a professional template you can use for all your MySQL scripts:

SQL — Professional Script Header Template 
1-- ============================================================
2-- Script  : 001_create_ecommerce_schema.sql
3-- Database: ecommerce_db
4-- Author  : Rahul Gupta
5-- Created : 2025-07-01
6-- Modified: 2025-07-15 — Added payments table (v1.2)
7-- Purpose : Initial schema creation for the e-commerce platform.
8--           Creates all core tables with constraints and indexes.
9-- WARNING : This script is destructive — it drops and recreates
10--           the ecommerce_db database. DO NOT run on production
11--           without a full backup.
12-- Requires: MySQL 8.0+
13-- ============================================================
14
15-- ── Section 1: Database Setup ────────────────────────────
16DROP DATABASE IF EXISTS ecommerce_db;
17CREATE DATABASE ecommerce_db
18    CHARACTER SET utf8mb4
19    COLLATE       utf8mb4_0900_ai_ci;
20USE ecommerce_db;
21
22-- ── Section 2: Core Tables ───────────────────────────────
23-- customers table: stores all registered users
24CREATE TABLE customers (
25    customer_id  INT           NOT NULL AUTO_INCREMENT,
26    email        VARCHAR(255) NOT NULL UNIQUE,
27    PRIMARY KEY  (customer_id)
28);  -- PK auto-increments from 1

MySQL-Specific: Executable Comments (/*! */)

MySQL has a special variant of block comments — the executable comment /*! ... */ — that is unique to MySQL. Code inside these comments is executed by MySQL but treated as a comment (and ignored) by other SQL databases. This is commonly used in mysqldump export files to include MySQL-specific syntax that won’t break other databases.

SQL — MySQL Executable Comments 
1-- Basic executable comment: MySQL runs this, other DBs ignore it
2/*!40101 SET NAMES utf8mb4 */;
3-- The number 40101 means: only execute on MySQL 4.01.01 or higher
4
5-- Commonly seen in mysqldump output:
6/*!40103 SET TIME_ZONE='+00:00' */;
7/*!40014 SET FOREIGN_KEY_CHECKS=0 */;
8
9-- Without a version number: MySQL always executes it
10/*!ENGINE=InnoDB*/  -- MySQL sees ENGINE=InnoDB; other DBs ignore it

You won’t write executable comments in daily work — they appear mainly in mysqldump backup files. But you’ll encounter them constantly when importing or reviewing database exports, so it’s important to recognise what they are and know not to delete them.

Key Takeaways

  • MySQL supports three comment styles: -- (double-dash, ANSI standard), # (hash, MySQL-specific), and /* ... */ (block, ANSI standard).
  • The double-dash style requires a space after the dashes: -- comment ✓    --comment ✗
  • Block comments /* ... */ are the only style that can span multiple lines or appear inline within a statement.
  • Use -- for portable scripts (works in MySQL, PostgreSQL, Oracle, SQL Server). Use # only in MySQL-specific contexts.
  • Every production SQL script should have a header block comment with the script name, author, date, purpose, and any warnings.
  • MySQL’s /*! ... */ executable comments run in MySQL but are ignored by other databases — commonly found in mysqldump exports.

What’s Next?

In Chapter 2.4 — Executing SQL from a File, we’ll learn how to save SQL scripts in .sql files and run them using the source command in the MySQL CLI and the mysql command-line tool — an essential skill for version-controlled database migrations and automated deployments.