SQL Comments & Query Documentation: Single-Line, Multi-Line & Rules

Clean database code requires clear, maintainable documentation. SQL Comments are explanatory notes written directly inside your database scripts that are completely ignored by the database query engine. They clarify business logic, explain non-intuitive join conditions, document table migrations, and help developers debug complex queries.

1. Single-Line Comments (--)

In standard ANSI SQL, a single-line comment begins with two consecutive hyphens (--) followed by at least one space. Anything after the hyphens until the end of that line is ignored by the database:

-- Retrieve all active BCA students
SELECT student_id, student_name, gpa
FROM students
WHERE status = 'Active'; -- Inline comment: Ignore alumni and dropped students

2. Multi-Line Comments (/* ... */)

For extensive query explanations, documentation headers, or disabling entire SQL blocks during testing, use C-style multi-line comments bounded by /* and */:

/*
======================================================================
Author:       Veewom Database Engineering Team
Date:         2026-11-06
Purpose:      Calculate monthly revenue per department for finance audit
Target RDBMS: MySQL 8.0+ / PostgreSQL 16+
======================================================================
*/
SELECT 
    d.dept_name,
    COUNT(e.emp_id) AS total_employees,
    SUM(e.salary) AS total_payroll
FROM departments d
JOIN employees e ON d.dept_id = e.dept_id
GROUP BY d.dept_name;

Using Comments for Query Debugging

Comments are frequently used by developers to isolate query bottlenecks without rewriting code:

SELECT emp_name, salary, department
FROM employees
WHERE salary > 60000
  -- AND department = 'IT'  /* Temporarily commented out to inspect all depts */
ORDER BY salary DESC;

Best Practices for SQL Documentation

• Explain the "Why", Not the "What": Avoid obvious comments like -- Select all students. Instead, explain the business reason: -- Filter only students eligible for merit scholarship (GPA >= 3.8).

• Document Complex Regular Expressions & Math: If you use complicated math formulas or custom substring offsets, document the logic clearly so future engineers understand the code.

• Keep Migration Scripts Versioned: Always header your DDL migration files with author name, ticket number, and release date.

Congratulations! You have completed Module 1 (Fundamentals & Core RDBMS). Now let us advance to Module 2 and master schema management starting with CREATE & DROP DATABASE!