MySQL Comments

Types of Comments

-- This is a comment
SELECT * FROM users;
-- Another comment

# This is also a comment
SELECT * FROM products;
# Works the same as --

/* This comment
   spans multiple
   lines */
SELECT * FROM orders;

SELECT 
    name,  -- Customer name
    email  -- Contact email
FROM customers;

🔹 Single-Line Comments with --

The double dash (--) creates a comment from that point to the end of the line. It's perfect for quick notes, explaining individual lines, or temporarily disabling a single line of code. Remember to add a space after the dashes for better readability.

-- Retrieve all active customers
SELECT 
    customer_id,
    customer_name,
    email
FROM customers
WHERE status = 'active';  -- Filter for active only

-- This query was created on 2024-01-15
-- Author: Database Team

🔹 Single-Line Comments with #

The hash symbol (#) works exactly like double dashes for single-line comments. It's commonly used in MySQL scripts and configuration files. Choose one style and use it consistently throughout your project for cleaner, more professional-looking code.

# Database: sales_db
# Table: products
# Purpose: Get all products with low stock

SELECT 
    product_id,
    product_name,
    stock_quantity  # Current inventory level
FROM products
WHERE stock_quantity < 10;  # Low stock threshold

🔹 Multi-Line Comments

Multi-line comments start with /* and end with */. They're ideal for longer explanations, documentation headers, or commenting out entire blocks of code during testing. Everything between the symbols is ignored, even if it spans dozens of lines.

/*
 * Query: Monthly Sales Report
 * Description: Calculates total sales by month for the current year
 * Author: Sales Team
 * Date: 2024-01-15
 * Last Modified: 2024-01-20
 */

SELECT 
    MONTH(order_date) AS month,
    COUNT(*) AS total_orders,
    SUM(total_amount) AS total_sales
FROM orders
WHERE YEAR(order_date) = 2024
GROUP BY MONTH(order_date);

/* 
Note: This query excludes cancelled orders
TODO: Add customer segmentation in next version
*/

🔹 Commenting Out Code

Comments are invaluable for temporarily disabling code during debugging or testing. Instead of deleting lines you might need later, comment them out. This lets you quickly test different query variations or isolate problems without losing your original code.

SELECT 
    product_name,
    price,
    stock_quantity
FROM products
WHERE category = 'Electronics'
-- AND price > 100  -- Temporarily disabled price filter
-- AND stock_quantity > 0  -- Testing with all products
ORDER BY price DESC;

/*
-- Alternative sorting options (commented out)
ORDER BY product_name ASC;
ORDER BY stock_quantity DESC;
*/

🔹 Best Practices for Comments

Good comments explain why, not what. Your code shows what it does, but comments should explain the reasoning, business rules, or special cases. Keep comments up-to-date, remove obsolete ones, and use them to make complex queries understandable for future developers.

-- GOOD: Explains the business rule
-- Customers with 3+ orders in 30 days qualify for VIP status
SELECT customer_id, COUNT(*) as order_count
FROM orders
WHERE order_date >= DATE_SUB(NOW(), INTERVAL 30 DAY)
GROUP BY customer_id
HAVING COUNT(*) >= 3;

-- BAD: States the obvious
-- Select customer_id and count orders
-- Group by customer_id

/*
 * BEST PRACTICE TIPS:
 * 1. Explain complex business logic
 * 2. Document assumptions and limitations
 * 3. Note performance considerations
 * 4. Include author and date for major queries
 * 5. Keep comments concise and relevant
 */

🔹 Practical Examples

Real-world examples showing how professional developers use comments. These demonstrate documenting complex queries, explaining business rules, marking temporary changes, and creating clear, maintainable SQL code that teams can understand and modify confidently over time.

-- Example 1: Documenting a complex query
/*
 * Customer Lifetime Value (CLV) Calculation
 * Formula: Total purchases / Customer age in months
 * Excludes: Refunded orders and test accounts
 */
SELECT 
    c.customer_id,
    c.customer_name,
    SUM(o.total_amount) AS total_spent,  -- Lifetime purchases
    TIMESTAMPDIFF(MONTH, c.registration_date, NOW()) AS months_active,
    SUM(o.total_amount) / TIMESTAMPDIFF(MONTH, c.registration_date, NOW()) AS clv
FROM customers c
JOIN orders o ON c.customer_id = o.customer_id
WHERE o.status != 'refunded'  -- Exclude refunds
    AND c.is_test_account = 0  -- Exclude test data
GROUP BY c.customer_id;

-- Example 2: Temporary debugging
SELECT * FROM products
WHERE category = 'Electronics'
-- LIMIT 10;  -- TODO: Remove limit before production deployment

-- Example 3: Version notes
/*
 * Version 2.0 - Added discount calculation
 * Version 1.5 - Fixed date range bug
 * Version 1.0 - Initial release
 */