SQL Comment Styles: Single-Line, Block, and Header Documentation

By Sharon Ben-Moshe · October 12, 2026 · 1 min read

Sharon Ben-Moshe is the founder of sqlfmt, a browser-based SQL formatter and validator with misspelled-keyword suggestions across PostgreSQL, MySQL, SQLite, SQL Server, and BigQuery.

Discover best practices for writing clean SQL comments. Master single-line (--) dashes, block (/* */) comments, header blocks, and inline explanations.

Quick answer

SQL supports two comment formats: single-line comments starting with two hyphens followed by a space ('-- comment') and multi-line block comments enclosed between '/*' and '*/'. Use block comments for file header documentation and single-line comments on their own preceding lines to explain 'why' a query filter or join condition exists.

FAQs

Why is a trailing space required after '--' in SQL?

The ANSI SQL standard requires a whitespace character immediately following the two dashes (`-- `). While some engines tolerate `--comment` without a space, others treat it as a syntax error or a token operator.

Can block comments be nested in SQL?

PostgreSQL and SQLite support nested block comments (`/* outer /* inner */ outer */`). However, MySQL and SQL Server do not support nested block comments and will throw syntax errors when encountering the first closing `*/`.

Do SQL comments impact query performance?

No. The SQL parser strips comments during lexical analysis before compiling the query plan. However, comments inside dynamic SQL strings do increase network payload size.

Where should inline comments be placed in formatted SQL?

Place comments on their own line immediately preceding the code they document. Placing comments at the end of code lines often causes automated formatters to wrap lines awkwardly.

SQL Formatting

Building an Enterprise SQL Style Guide: Formatting Standards, Linting, and Team Conventions

By Sharon Ben-Moshe · Oct 13, 2026

The complete blueprint for an enterprise SQL style guide. Standardize formatting, keyword casing, indentation, naming conventions, and CI linting.

Read post

SQL Formatting

The Master Guide to SQL Common Table Expressions (CTEs): Syntax, Optimization Fences, and Recursion

By Sharon Ben-Moshe · Oct 13, 2026

The definitive guide to SQL Common Table Expressions (CTEs). Master chaining, recursive hierarchies, data-modifying CTEs, and optimization fences.

Read post

SQL Formatting

Try it now

Paste your SQL into sqlfmt — format, validate, and catch typos free in your browser.

Open SQL Formatter →

Key takeaways

Always include a space after the double hyphens (-- comment) for strict ANSI compliance.

Use file header blocks to document migration purpose, ticket ID, author, and rollback steps.

Comment on the 'why' (business requirement, edge case), not the 'what' (obvious syntax).

Place comments on their own separate line directly above the clause rather than trailing at the end of lines.

File header comment conventions

Every production migration or stored script should begin with a clean doc-block explaining its context:

Standardized SQL migration header comment

/*==============================================================================
  Script:       20261012_add_fraud_status_to_transactions.sql
  Ticket:       JIRA-8419
  Author:       Data Engineering Team
  Created:      2026-10-12
  Description:  Adds fraud_score and status flags to core.transactions.
                Includes partial index for rapid lookup of pending reviews.
==============================================================================*/

Effective inline commenting: Explain the 'Why'

Comments should never restate what the code already says. Focus on non-obvious domain logic, tax rules, or timezone corrections:

Poor versus high-value SQL comments

-- BAD: Merely restates the obvious code
-- Select customer and orders
SELECT
  c.id,
  o.order_total
FROM customers c
-- Join on customer id
JOIN orders o ON c.id = o.customer_id
-- Filter status not refunded
WHERE o.status != 'refunded';

-- GOOD: Explains non-obvious business rules and edge cases
SELECT
  c.id,
  o.order_total
FROM customers c
JOIN orders o ON c.id = o.customer_id
-- Exclude chargebacks and test sandbox transactions per Accounting Policy 4.2
WHERE o.status != 'refunded'
  AND o.amount > 0.00
  AND c.is_test_account = false;

SQL Comment Styles: Single-Line, Block, and Header Documentation

Quick answer

FAQs

Why is a trailing space required after '--' in SQL?

Can block comments be nested in SQL?

Do SQL comments impact query performance?

Where should inline comments be placed in formatted SQL?

Building an Enterprise SQL Style Guide: Formatting Standards, Linting, and Team Conventions

The Master Guide to SQL Common Table Expressions (CTEs): Syntax, Optimization Fences, and Recursion

How to Format Recursive CTEs in SQL: Hierarchical Query Structure

Key takeaways

File header comment conventions

Effective inline commenting: Explain the 'Why'

Official references

Quick answer

FAQs

Why is a trailing space required after '--' in SQL?

Can block comments be nested in SQL?

Do SQL comments impact query performance?

Where should inline comments be placed in formatted SQL?

Keep reading

Building an Enterprise SQL Style Guide: Formatting Standards, Linting, and Team Conventions

The Master Guide to SQL Common Table Expressions (CTEs): Syntax, Optimization Fences, and Recursion

How to Format Recursive CTEs in SQL: Hierarchical Query Structure

Key takeaways

File header comment conventions

Effective inline commenting: Explain the 'Why'

Related SQL guides

Official references