An SQL comment adds helpful context to a query without affecting execution. Use comments to explain a query’s purpose, record an author and date, or guide the next person who maintains the script. section 4.3
Choose a comment style that makes the boundaries and intent clear:
- Use two consecutive hyphens for an inline comment; the comment continues to the next carriage return. section 4.3
- In MySQL, use # for an inline comment, but remember that another RDBMS may not recognize it. section 4.3
- Use /* and */ for comments spanning several lines or for reusable code, because the beginning and end are clearly marked. section 4.3 section 4.5
Explain a query’s purpose
/* This query returns 3 TitleNames ...with the most recent PublicationDate ...excluding the single most recent TitleName */ SELECT TitleName, PublicationDate FROM title ORDER BY PublicationDate DESC LIMIT 3 OFFSET 1; The database ignores the explanatory lines and executes the SELECT statement. A clear comment prevents readers from having to infer why the query sorts, limits, and skips rows. section 4.3
/*
# This query returns 3 random titles, but it wasn't what we needed
SELECT
TitleName,
PublicationDate
FROM title
LIMIT 3;
*/
-- This is the updated query, now ordered by most recent PublicationDate
SELECT
TitleName,
PublicationDate
FROM title
ORDER BY PublicationDate DESC
LIMIT 3;
Compare an outdated query commented out beside its replacement, showing how comments preserve context while keeping an alternative from executing. section 4.3
